1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
26 #include "dbus-signature.h"
27 #include "dbus-marshal-recursive.h"
28 #include "dbus-marshal-basic.h"
29 #include "dbus-internals.h"
30 #include "dbus-test.h"
33 * Implementation details of #DBusSignatureIter, all fields are private
37 const char *pos; /**< current position in the signature string */
38 unsigned int finished : 1; /**< true if we are at the end iter */
39 unsigned int in_array : 1; /**< true if we are a subiterator pointing to an array's element type */
40 } DBusSignatureRealIter;
42 /** macro that checks whether a typecode is a container type */
43 #define TYPE_IS_CONTAINER(typecode) \
44 ((typecode) == DBUS_TYPE_STRUCT || \
45 (typecode) == DBUS_TYPE_DICT_ENTRY || \
46 (typecode) == DBUS_TYPE_VARIANT || \
47 (typecode) == DBUS_TYPE_ARRAY)
51 * @defgroup DBusSignature Type signature parsing
53 * @brief Parsing D-Bus type signatures
58 * Initializes a #DBusSignatureIter for reading a type signature. This
59 * function is not safe to use on invalid signatures; be sure to
60 * validate potentially invalid signatures with dbus_signature_validate
61 * before using this function.
63 * @param iter pointer to an iterator to initialize
64 * @param signature the type signature
67 dbus_signature_iter_init (DBusSignatureIter *iter,
68 const char *signature)
70 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
72 real_iter->pos = signature;
73 real_iter->finished = FALSE;
74 real_iter->in_array = FALSE;
78 * Returns the current type pointed to by the iterator.
79 * If the iterator is pointing at a type code such as 's', then
80 * it will be returned directly.
82 * However, when the parser encounters a container type start
83 * character such as '(' for a structure, the corresponding type for
84 * the container will be returned, e.g. DBUS_TYPE_STRUCT, not '('.
85 * In this case, you should initialize a sub-iterator with
86 * dbus_signature_iter_recurse() to parse the container type.
88 * @param iter pointer to an iterator
89 * @returns current type (e.g. #DBUS_TYPE_STRING, #DBUS_TYPE_ARRAY)
92 dbus_signature_iter_get_current_type (const DBusSignatureIter *iter)
94 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
96 return _dbus_first_type_in_signature_c_str (real_iter->pos, 0);
100 * Returns the signature of the single complete type starting at the
103 * For example, if the iterator is pointing at the start of "(ii)ii"
104 * (which is "a struct of two ints, followed by an int, followed by an
105 * int"), then "(ii)" would be returned. If the iterator is pointing at
106 * one of the "i" then just that "i" would be returned.
108 * @param iter pointer to an iterator
109 * @returns current signature; or #NULL if no memory. Should be freed with dbus_free()
112 dbus_signature_iter_get_signature (const DBusSignatureIter *iter)
114 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
119 if (!_dbus_string_init (&str))
123 _dbus_type_signature_next (real_iter->pos, &pos);
125 if (!_dbus_string_append_len (&str, real_iter->pos, pos))
127 if (!_dbus_string_steal_data (&str, &ret))
129 _dbus_string_free (&str);
135 * Convenience function for returning the element type of an array;
136 * This function allows you to avoid initializing a sub-iterator and
137 * getting its current type.
139 * Undefined behavior results if you invoke this function when the
140 * current type of the iterator is not #DBUS_TYPE_ARRAY.
142 * @param iter pointer to an iterator
143 * @returns current array element type
146 dbus_signature_iter_get_element_type (const DBusSignatureIter *iter)
148 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
150 _dbus_return_val_if_fail (dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
152 return _dbus_first_type_in_signature_c_str (real_iter->pos, 1);
156 * Skip to the next value on this "level". e.g. the next field in a
157 * struct, the next value in an array. Returns #FALSE at the end of the
160 * @param iter the iterator
161 * @returns FALSE if nothing more to read at or below this level
164 dbus_signature_iter_next (DBusSignatureIter *iter)
166 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
168 if (real_iter->finished)
174 if (real_iter->in_array)
176 real_iter->finished = TRUE;
181 _dbus_type_signature_next (real_iter->pos, &pos);
182 real_iter->pos += pos;
184 if (*real_iter->pos == DBUS_STRUCT_END_CHAR
185 || *real_iter->pos == DBUS_DICT_ENTRY_END_CHAR)
187 real_iter->finished = TRUE;
191 return *real_iter->pos != DBUS_TYPE_INVALID;
196 * Initialize a new iterator pointing to the first type in the current
199 * The results are undefined when calling this if the current type is
200 * a non-container (i.e. if dbus_type_is_container() returns #FALSE
201 * for the result of dbus_signature_iter_get_current_type()).
203 * @param iter the current interator
204 * @param subiter an iterator to initialize pointing to the first child
207 dbus_signature_iter_recurse (const DBusSignatureIter *iter,
208 DBusSignatureIter *subiter)
210 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
211 DBusSignatureRealIter *real_sub_iter = (DBusSignatureRealIter *) subiter;
213 _dbus_return_if_fail (dbus_type_is_container (dbus_signature_iter_get_current_type (iter)));
215 *real_sub_iter = *real_iter;
216 real_sub_iter->in_array = FALSE;
217 real_sub_iter->pos++;
219 if (dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY)
220 real_sub_iter->in_array = TRUE;
224 * Check a type signature for validity. Remember that #NULL can always
225 * be passed instead of a DBusError*, if you don't care about having
226 * an error name and message.
228 * @param signature a potentially invalid type signature
229 * @param error error return
230 * @returns #TRUE if signature is valid or #FALSE if an error is set
233 dbus_signature_validate (const char *signature,
240 _dbus_string_init_const (&str, signature);
241 reason = _dbus_validate_signature_with_reason (&str, 0, _dbus_string_get_length (&str));
243 if (reason == DBUS_VALID)
247 dbus_set_error (error, DBUS_ERROR_INVALID_SIGNATURE, "%s",
248 _dbus_validity_to_error_message (reason));
254 * Check that a type signature is both valid and contains exactly one
255 * complete type. "One complete type" means a single basic type,
256 * array, struct, or dictionary, though the struct or array may be
257 * arbitrarily recursive and complex. More than one complete type
258 * would mean for example "ii" or two integers in sequence.
260 * @param signature a potentially invalid type signature
261 * @param error error return
262 * @returns #TRUE if signature is valid and has exactly one complete type
265 dbus_signature_validate_single (const char *signature,
268 DBusSignatureIter iter;
270 if (!dbus_signature_validate (signature, error))
273 dbus_signature_iter_init (&iter, signature);
274 if (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_INVALID)
276 if (!dbus_signature_iter_next (&iter))
279 dbus_set_error (error, DBUS_ERROR_INVALID_SIGNATURE, "Exactly one complete type required in signature");
284 * A "container type" can contain basic types, or nested
285 * container types. #DBUS_TYPE_INVALID is not a container type.
287 * It is an error to pass an invalid type-code, other than DBUS_TYPE_INVALID,
288 * to this function. The valid type-codes are defined by dbus-protocol.h
289 * and can be checked with dbus_type_is_valid().
291 * @param typecode either a valid type-code or DBUS_TYPE_INVALID
292 * @returns #TRUE if type is a container
295 dbus_type_is_container (int typecode)
297 /* only reasonable (non-line-noise) typecodes are allowed */
298 _dbus_return_val_if_fail (dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
300 return TYPE_IS_CONTAINER (typecode);
304 * A "basic type" is a somewhat arbitrary concept, but the intent is
305 * to include those types that are fully-specified by a single
306 * typecode, with no additional type information or nested values. So
307 * all numbers and strings are basic types and structs, arrays, and
308 * variants are not basic types. #DBUS_TYPE_INVALID is not a basic
311 * It is an error to pass an invalid type-code, other than DBUS_TYPE_INVALID,
312 * to this function. The valid type-codes are defined by dbus-protocol.h
313 * and can be checked with dbus_type_is_valid().
315 * @param typecode either a valid type-code or DBUS_TYPE_INVALID
316 * @returns #TRUE if type is basic
319 dbus_type_is_basic (int typecode)
321 /* only reasonable (non-line-noise) typecodes are allowed */
322 _dbus_return_val_if_fail (dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
325 /* everything that isn't invalid or a container */
326 return !(typecode == DBUS_TYPE_INVALID || TYPE_IS_CONTAINER (typecode));
330 * Tells you whether values of this type can change length if you set
331 * them to some other value. For this purpose, you assume that the
332 * first byte of the old and new value would be in the same location,
333 * so alignment padding is not a factor.
335 * This function is useful to determine whether
336 * dbus_message_iter_get_fixed_array() may be used.
338 * Some structs are fixed-size (if they contain only fixed-size types)
339 * but struct is not considered a fixed type for purposes of this
342 * It is an error to pass an invalid type-code, other than DBUS_TYPE_INVALID,
343 * to this function. The valid type-codes are defined by dbus-protocol.h
344 * and can be checked with dbus_type_is_valid().
346 * @param typecode either a valid type-code or DBUS_TYPE_INVALID
347 * @returns #FALSE if the type can occupy different lengths
350 dbus_type_is_fixed (int typecode)
352 /* only reasonable (non-line-noise) typecodes are allowed */
353 _dbus_return_val_if_fail (dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
359 case DBUS_TYPE_BOOLEAN:
360 case DBUS_TYPE_INT16:
361 case DBUS_TYPE_UINT16:
362 case DBUS_TYPE_INT32:
363 case DBUS_TYPE_UINT32:
364 case DBUS_TYPE_INT64:
365 case DBUS_TYPE_UINT64:
366 case DBUS_TYPE_DOUBLE:
367 case DBUS_TYPE_UNIX_FD:
375 * Return #TRUE if the argument is a valid typecode.
376 * #DBUS_TYPE_INVALID surprisingly enough is not considered valid, and
377 * random unknown bytes aren't either. This function is safe with
380 * @param typecode a potential type-code
381 * @returns #TRUE if valid
384 dbus_type_is_valid (int typecode)
389 case DBUS_TYPE_BOOLEAN:
390 case DBUS_TYPE_INT16:
391 case DBUS_TYPE_UINT16:
392 case DBUS_TYPE_INT32:
393 case DBUS_TYPE_UINT32:
394 case DBUS_TYPE_INT64:
395 case DBUS_TYPE_UINT64:
396 case DBUS_TYPE_DOUBLE:
397 case DBUS_TYPE_STRING:
398 case DBUS_TYPE_OBJECT_PATH:
399 case DBUS_TYPE_SIGNATURE:
400 case DBUS_TYPE_ARRAY:
401 case DBUS_TYPE_STRUCT:
402 case DBUS_TYPE_DICT_ENTRY:
403 case DBUS_TYPE_VARIANT:
404 case DBUS_TYPE_UNIX_FD:
412 /** @} */ /* end of DBusSignature group */
414 #ifdef DBUS_ENABLE_EMBEDDED_TESTS
417 * @ingroup DBusSignatureInternals
418 * Unit test for DBusSignature.
420 * @returns #TRUE on success.
423 _dbus_signature_test (void)
425 DBusSignatureIter iter;
426 DBusSignatureIter subiter;
427 DBusSignatureIter subsubiter;
428 DBusSignatureIter subsubsubiter;
432 _DBUS_STATIC_ASSERT (sizeof (DBusSignatureIter) >= sizeof (DBusSignatureRealIter));
435 _dbus_assert (dbus_signature_validate (sig, NULL));
436 _dbus_assert (!dbus_signature_validate_single (sig, NULL));
437 dbus_signature_iter_init (&iter, sig);
438 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_INVALID);
440 sig = DBUS_TYPE_STRING_AS_STRING;
441 _dbus_assert (dbus_signature_validate (sig, NULL));
442 _dbus_assert (dbus_signature_validate_single (sig, NULL));
443 dbus_signature_iter_init (&iter, sig);
444 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRING);
446 sig = DBUS_TYPE_STRING_AS_STRING DBUS_TYPE_BYTE_AS_STRING;
447 _dbus_assert (dbus_signature_validate (sig, NULL));
448 dbus_signature_iter_init (&iter, sig);
449 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRING);
450 boolres = dbus_signature_iter_next (&iter);
451 _dbus_assert (boolres);
452 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_BYTE);
454 sig = DBUS_TYPE_UINT16_AS_STRING
455 DBUS_STRUCT_BEGIN_CHAR_AS_STRING
456 DBUS_TYPE_STRING_AS_STRING
457 DBUS_TYPE_UINT32_AS_STRING
458 DBUS_TYPE_VARIANT_AS_STRING
459 DBUS_TYPE_DOUBLE_AS_STRING
460 DBUS_STRUCT_END_CHAR_AS_STRING;
461 _dbus_assert (dbus_signature_validate (sig, NULL));
462 dbus_signature_iter_init (&iter, sig);
463 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
464 boolres = dbus_signature_iter_next (&iter);
465 _dbus_assert (boolres);
466 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
467 dbus_signature_iter_recurse (&iter, &subiter);
468 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRING);
469 boolres = dbus_signature_iter_next (&subiter);
470 _dbus_assert (boolres);
471 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
472 boolres = dbus_signature_iter_next (&subiter);
473 _dbus_assert (boolres);
474 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_VARIANT);
475 boolres = dbus_signature_iter_next (&subiter);
476 _dbus_assert (boolres);
477 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_DOUBLE);
479 sig = DBUS_TYPE_UINT16_AS_STRING
480 DBUS_STRUCT_BEGIN_CHAR_AS_STRING
481 DBUS_TYPE_UINT32_AS_STRING
482 DBUS_TYPE_BYTE_AS_STRING
483 DBUS_TYPE_ARRAY_AS_STRING
484 DBUS_TYPE_ARRAY_AS_STRING
485 DBUS_TYPE_DOUBLE_AS_STRING
486 DBUS_STRUCT_BEGIN_CHAR_AS_STRING
487 DBUS_TYPE_BYTE_AS_STRING
488 DBUS_STRUCT_END_CHAR_AS_STRING
489 DBUS_STRUCT_END_CHAR_AS_STRING;
490 _dbus_assert (dbus_signature_validate (sig, NULL));
491 dbus_signature_iter_init (&iter, sig);
492 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
493 boolres = dbus_signature_iter_next (&iter);
494 _dbus_assert (boolres);
495 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
496 dbus_signature_iter_recurse (&iter, &subiter);
497 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
498 boolres = dbus_signature_iter_next (&subiter);
499 _dbus_assert (boolres);
500 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_BYTE);
501 boolres = dbus_signature_iter_next (&subiter);
502 _dbus_assert (boolres);
503 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_ARRAY);
504 _dbus_assert (dbus_signature_iter_get_element_type (&subiter) == DBUS_TYPE_ARRAY);
506 dbus_signature_iter_recurse (&subiter, &subsubiter);
507 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_ARRAY);
508 _dbus_assert (dbus_signature_iter_get_element_type (&subsubiter) == DBUS_TYPE_DOUBLE);
510 dbus_signature_iter_recurse (&subsubiter, &subsubsubiter);
511 _dbus_assert (dbus_signature_iter_get_current_type (&subsubsubiter) == DBUS_TYPE_DOUBLE);
512 boolres = dbus_signature_iter_next (&subiter);
513 _dbus_assert (boolres);
514 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRUCT);
515 dbus_signature_iter_recurse (&subiter, &subsubiter);
516 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_BYTE);
518 sig = DBUS_TYPE_ARRAY_AS_STRING
519 DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
520 DBUS_TYPE_INT16_AS_STRING
521 DBUS_TYPE_STRING_AS_STRING
522 DBUS_DICT_ENTRY_END_CHAR_AS_STRING
523 DBUS_TYPE_VARIANT_AS_STRING;
524 _dbus_assert (dbus_signature_validate (sig, NULL));
525 _dbus_assert (!dbus_signature_validate_single (sig, NULL));
526 dbus_signature_iter_init (&iter, sig);
527 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_ARRAY);
528 _dbus_assert (dbus_signature_iter_get_element_type (&iter) == DBUS_TYPE_DICT_ENTRY);
530 dbus_signature_iter_recurse (&iter, &subiter);
531 dbus_signature_iter_recurse (&subiter, &subsubiter);
532 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_INT16);
533 boolres = dbus_signature_iter_next (&subsubiter);
534 _dbus_assert (boolres);
535 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_STRING);
536 boolres = dbus_signature_iter_next (&subsubiter);
537 _dbus_assert (!boolres);
539 boolres = dbus_signature_iter_next (&iter);
540 _dbus_assert (boolres);
541 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_VARIANT);
542 boolres = dbus_signature_iter_next (&iter);
543 _dbus_assert (!boolres);
545 sig = DBUS_TYPE_DICT_ENTRY_AS_STRING;
546 _dbus_assert (!dbus_signature_validate (sig, NULL));
548 sig = DBUS_TYPE_ARRAY_AS_STRING;
549 _dbus_assert (!dbus_signature_validate (sig, NULL));
551 sig = DBUS_TYPE_UINT32_AS_STRING
552 DBUS_TYPE_ARRAY_AS_STRING;
553 _dbus_assert (!dbus_signature_validate (sig, NULL));
555 sig = DBUS_TYPE_ARRAY_AS_STRING
556 DBUS_TYPE_DICT_ENTRY_AS_STRING;
557 _dbus_assert (!dbus_signature_validate (sig, NULL));
559 sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING;
560 _dbus_assert (!dbus_signature_validate (sig, NULL));
562 sig = DBUS_DICT_ENTRY_END_CHAR_AS_STRING;
563 _dbus_assert (!dbus_signature_validate (sig, NULL));
565 sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
566 DBUS_TYPE_INT32_AS_STRING;
567 _dbus_assert (!dbus_signature_validate (sig, NULL));
569 sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
570 DBUS_TYPE_INT32_AS_STRING
571 DBUS_TYPE_STRING_AS_STRING;
572 _dbus_assert (!dbus_signature_validate (sig, NULL));
574 sig = DBUS_STRUCT_END_CHAR_AS_STRING
575 DBUS_STRUCT_BEGIN_CHAR_AS_STRING;
576 _dbus_assert (!dbus_signature_validate (sig, NULL));
578 sig = DBUS_STRUCT_BEGIN_CHAR_AS_STRING
579 DBUS_TYPE_BOOLEAN_AS_STRING;
580 _dbus_assert (!dbus_signature_validate (sig, NULL));
584 _dbus_assert_not_reached ("out of memory");