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 * @defgroup DBusSignature Type signature parsing
40 * @brief Parsing D-Bus type signatures
45 * Initializes a #DBusSignatureIter for reading a type signature. This
46 * function is not safe to use on invalid signatures; be sure to
47 * validate potentially invalid signatures with dbus_signature_validate
48 * before using this function.
50 * @param iter pointer to an iterator to initialize
51 * @param signature the type signature
54 dbus_signature_iter_init (DBusSignatureIter *iter,
55 const char *signature)
57 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
59 real_iter->pos = signature;
60 real_iter->finished = FALSE;
61 real_iter->in_array = FALSE;
65 * Returns the current type pointed to by the iterator.
66 * If the iterator is pointing at a type code such as 's', then
67 * it will be returned directly.
69 * However, when the parser encounters a container type start
70 * character such as '(' for a structure, the corresponding type for
71 * the container will be returned, e.g. DBUS_TYPE_STRUCT, not '('.
72 * In this case, you should initialize a sub-iterator with
73 * dbus_signature_iter_recurse to parse the container type.
75 * @param iter pointer to an iterator
76 * @returns current type (e.g. DBUS_TYPE_STRING, DBUS_TYPE_ARRAY)
79 dbus_signature_iter_get_current_type (const DBusSignatureIter *iter)
81 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
83 return _dbus_first_type_in_signature_c_str (real_iter->pos, 0);
87 * Returns the full type signature represented by the current
88 * iterator as a C string.
90 * @param iter pointer to an iterator
91 * @returns current signature; or NULL on OOM. Should be freed with #dbus_free
94 dbus_signature_iter_get_signature (const DBusSignatureIter *iter)
96 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
101 if (!_dbus_string_init (&str))
105 _dbus_type_signature_next (real_iter->pos, &pos);
107 if (!_dbus_string_append_len (&str, real_iter->pos, pos))
109 if (!_dbus_string_steal_data (&str, &ret))
111 _dbus_string_free (&str);
117 * Convenience function for returning the element type of an array;
118 * This function allows you to avoid initializing a sub-iterator and
119 * getting its current type.
121 * It is an error to invoke this function if the current type of the
122 * iterator is not DBUS_TYPE_ARRAY.
124 * @param iter pointer to an iterator
125 * @returns current array element type
128 dbus_signature_iter_get_element_type (const DBusSignatureIter *iter)
130 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
132 _dbus_return_val_if_fail (dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
134 return _dbus_first_type_in_signature_c_str (real_iter->pos, 1);
138 * Skip to the next value on this "level". e.g. the next field in a
139 * struct, the next value in an array. Returns FALSE at the end of the
142 * @param iter the iterator
143 * @returns FALSE if nothing more to read at or below this level
146 dbus_signature_iter_next (DBusSignatureIter *iter)
148 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
150 if (real_iter->finished)
156 if (real_iter->in_array)
158 real_iter->finished = TRUE;
163 _dbus_type_signature_next (real_iter->pos, &pos);
164 real_iter->pos += pos;
166 if (*real_iter->pos == DBUS_STRUCT_END_CHAR
167 || *real_iter->pos == DBUS_DICT_ENTRY_END_CHAR)
169 real_iter->finished = TRUE;
173 return *real_iter->pos != DBUS_TYPE_INVALID;
178 * Initialize a new iterator pointing to the first type current
179 * container. It's an error to call this if the current type is a
180 * non-container (i.e. if dbus_type_is_container returns FALSE).
182 * @param iter the current interator
183 * @param subiter an iterator to initialize pointing to the first child
186 dbus_signature_iter_recurse (const DBusSignatureIter *iter,
187 DBusSignatureIter *subiter)
189 DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
190 DBusSignatureRealIter *real_sub_iter = (DBusSignatureRealIter *) subiter;
192 _dbus_return_if_fail (dbus_type_is_container (dbus_signature_iter_get_current_type (iter)));
194 *real_sub_iter = *real_iter;
195 real_sub_iter->in_array = FALSE;
196 real_sub_iter->pos++;
198 if (dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY)
199 real_sub_iter->in_array = TRUE;
203 * Check a type signature for validity.
205 * @param signature a potentially invalid type signature
206 * @param error error return
207 * @returns TRUE iif signature is valid
210 dbus_signature_validate (const char *signature,
216 _dbus_string_init_const (&str, signature);
217 if (_dbus_validate_signature (&str, 0, _dbus_string_get_length (&str)))
219 dbus_set_error (error, DBUS_ERROR_INVALID_SIGNATURE, "Corrupt type signature");
224 * Check that a type signature is both valid and contains exactly
227 * @param signature a potentially invalid type signature
228 * @param error error return
229 * @returns TRUE iif signature is valid and has exactly one complete type
232 dbus_signature_validate_single (const char *signature,
235 DBusSignatureIter iter;
237 if (!dbus_signature_validate (signature, error))
240 dbus_signature_iter_init (&iter, signature);
241 if (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_INVALID)
243 if (!dbus_signature_iter_next (&iter))
246 dbus_set_error (error, DBUS_ERROR_INVALID_SIGNATURE, "Exactly one complete type required in signature");
250 /** macro that checks whether a typecode is a container type */
251 #define TYPE_IS_CONTAINER(typecode) \
252 ((typecode) == DBUS_TYPE_STRUCT || \
253 (typecode) == DBUS_TYPE_DICT_ENTRY || \
254 (typecode) == DBUS_TYPE_VARIANT || \
255 (typecode) == DBUS_TYPE_ARRAY)
258 * A "container type" can contain basic types, or nested
259 * container types. #DBUS_TYPE_INVALID is not a container type.
260 * This function will crash if passed a typecode that isn't
263 * @returns #TRUE if type is a container
266 dbus_type_is_container (int typecode)
268 /* only reasonable (non-line-noise) typecodes are allowed */
269 _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
271 return TYPE_IS_CONTAINER (typecode);
275 * A "basic type" is a somewhat arbitrary concept, but the intent
276 * is to include those types that are fully-specified by a single
277 * typecode, with no additional type information or nested
278 * values. So all numbers and strings are basic types and
279 * structs, arrays, and variants are not basic types.
280 * #DBUS_TYPE_INVALID is not a basic type.
282 * This function will crash if passed a typecode that isn't
285 * @returns #TRUE if type is basic
288 dbus_type_is_basic (int typecode)
290 /* only reasonable (non-line-noise) typecodes are allowed */
291 _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
294 /* everything that isn't invalid or a container */
295 return !(typecode == DBUS_TYPE_INVALID || TYPE_IS_CONTAINER (typecode));
299 * Tells you whether values of this type can change length if you set
300 * them to some other value. For this purpose, you assume that the
301 * first byte of the old and new value would be in the same location,
302 * so alignment padding is not a factor.
304 * This function is useful to determine whether #dbus_message_iter_get_fixed_array
307 * @returns #FALSE if the type can occupy different lengths
310 dbus_type_is_fixed (int typecode)
315 case DBUS_TYPE_BOOLEAN:
316 case DBUS_TYPE_INT16:
317 case DBUS_TYPE_UINT16:
318 case DBUS_TYPE_INT32:
319 case DBUS_TYPE_UINT32:
320 case DBUS_TYPE_INT64:
321 case DBUS_TYPE_UINT64:
322 case DBUS_TYPE_DOUBLE:
329 #ifdef DBUS_BUILD_TESTS
332 * @ingroup DBusSignatureInternals
333 * Unit test for DBusSignature.
335 * @returns #TRUE on success.
338 _dbus_signature_test (void)
340 DBusSignatureIter iter;
341 DBusSignatureIter subiter;
342 DBusSignatureIter subsubiter;
343 DBusSignatureIter subsubsubiter;
346 _dbus_assert (sizeof (DBusSignatureIter) >= sizeof (DBusSignatureRealIter));
349 _dbus_assert (dbus_signature_validate (sig, NULL));
350 _dbus_assert (!dbus_signature_validate_single (sig, NULL));
351 dbus_signature_iter_init (&iter, sig);
352 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_INVALID);
354 sig = DBUS_TYPE_STRING_AS_STRING;
355 _dbus_assert (dbus_signature_validate (sig, NULL));
356 _dbus_assert (dbus_signature_validate_single (sig, NULL));
357 dbus_signature_iter_init (&iter, sig);
358 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRING);
360 sig = DBUS_TYPE_STRING_AS_STRING DBUS_TYPE_BYTE_AS_STRING;
361 _dbus_assert (dbus_signature_validate (sig, NULL));
362 dbus_signature_iter_init (&iter, sig);
363 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRING);
364 _dbus_assert (dbus_signature_iter_next (&iter));
365 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_BYTE);
367 sig = DBUS_TYPE_UINT16_AS_STRING
368 DBUS_STRUCT_BEGIN_CHAR_AS_STRING
369 DBUS_TYPE_STRING_AS_STRING
370 DBUS_TYPE_UINT32_AS_STRING
371 DBUS_TYPE_VARIANT_AS_STRING
372 DBUS_TYPE_DOUBLE_AS_STRING
373 DBUS_STRUCT_END_CHAR_AS_STRING;
374 _dbus_assert (dbus_signature_validate (sig, NULL));
375 dbus_signature_iter_init (&iter, sig);
376 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
377 _dbus_assert (dbus_signature_iter_next (&iter));
378 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
379 dbus_signature_iter_recurse (&iter, &subiter);
380 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRING);
381 _dbus_assert (dbus_signature_iter_next (&subiter));
382 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
383 _dbus_assert (dbus_signature_iter_next (&subiter));
384 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_VARIANT);
385 _dbus_assert (dbus_signature_iter_next (&subiter));
386 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_DOUBLE);
388 sig = DBUS_TYPE_UINT16_AS_STRING
389 DBUS_STRUCT_BEGIN_CHAR_AS_STRING
390 DBUS_TYPE_UINT32_AS_STRING
391 DBUS_TYPE_BYTE_AS_STRING
392 DBUS_TYPE_ARRAY_AS_STRING
393 DBUS_TYPE_ARRAY_AS_STRING
394 DBUS_TYPE_DOUBLE_AS_STRING
395 DBUS_STRUCT_BEGIN_CHAR_AS_STRING
396 DBUS_TYPE_BYTE_AS_STRING
397 DBUS_STRUCT_END_CHAR_AS_STRING
398 DBUS_STRUCT_END_CHAR_AS_STRING;
399 _dbus_assert (dbus_signature_validate (sig, NULL));
400 dbus_signature_iter_init (&iter, sig);
401 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
402 _dbus_assert (dbus_signature_iter_next (&iter));
403 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
404 dbus_signature_iter_recurse (&iter, &subiter);
405 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
406 _dbus_assert (dbus_signature_iter_next (&subiter));
407 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_BYTE);
408 _dbus_assert (dbus_signature_iter_next (&subiter));
409 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_ARRAY);
410 _dbus_assert (dbus_signature_iter_get_element_type (&subiter) == DBUS_TYPE_ARRAY);
412 dbus_signature_iter_recurse (&subiter, &subsubiter);
413 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_ARRAY);
414 _dbus_assert (dbus_signature_iter_get_element_type (&subsubiter) == DBUS_TYPE_DOUBLE);
416 dbus_signature_iter_recurse (&subsubiter, &subsubsubiter);
417 _dbus_assert (dbus_signature_iter_get_current_type (&subsubsubiter) == DBUS_TYPE_DOUBLE);
418 _dbus_assert (dbus_signature_iter_next (&subiter));
419 _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRUCT);
420 dbus_signature_iter_recurse (&subiter, &subsubiter);
421 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_BYTE);
423 sig = DBUS_TYPE_ARRAY_AS_STRING
424 DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
425 DBUS_TYPE_INT16_AS_STRING
426 DBUS_TYPE_STRING_AS_STRING
427 DBUS_DICT_ENTRY_END_CHAR_AS_STRING
428 DBUS_TYPE_VARIANT_AS_STRING;
429 _dbus_assert (dbus_signature_validate (sig, NULL));
430 _dbus_assert (!dbus_signature_validate_single (sig, NULL));
431 dbus_signature_iter_init (&iter, sig);
432 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_ARRAY);
433 _dbus_assert (dbus_signature_iter_get_element_type (&iter) == DBUS_TYPE_DICT_ENTRY);
435 dbus_signature_iter_recurse (&iter, &subiter);
436 dbus_signature_iter_recurse (&subiter, &subsubiter);
437 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_INT16);
438 _dbus_assert (dbus_signature_iter_next (&subsubiter));
439 _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_STRING);
440 _dbus_assert (!dbus_signature_iter_next (&subsubiter));
442 _dbus_assert (dbus_signature_iter_next (&iter));
443 _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_VARIANT);
444 _dbus_assert (!dbus_signature_iter_next (&iter));
446 sig = DBUS_TYPE_DICT_ENTRY_AS_STRING;
447 _dbus_assert (!dbus_signature_validate (sig, NULL));
449 sig = DBUS_TYPE_ARRAY_AS_STRING;
450 _dbus_assert (!dbus_signature_validate (sig, NULL));
452 sig = DBUS_TYPE_UINT32_AS_STRING
453 DBUS_TYPE_ARRAY_AS_STRING;
454 _dbus_assert (!dbus_signature_validate (sig, NULL));
456 sig = DBUS_TYPE_ARRAY_AS_STRING
457 DBUS_TYPE_DICT_ENTRY_AS_STRING;
458 _dbus_assert (!dbus_signature_validate (sig, NULL));
460 sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING;
461 _dbus_assert (!dbus_signature_validate (sig, NULL));
463 sig = DBUS_DICT_ENTRY_END_CHAR_AS_STRING;
464 _dbus_assert (!dbus_signature_validate (sig, NULL));
466 sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
467 DBUS_TYPE_INT32_AS_STRING;
468 _dbus_assert (!dbus_signature_validate (sig, NULL));
470 sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
471 DBUS_TYPE_INT32_AS_STRING
472 DBUS_TYPE_STRING_AS_STRING;
473 _dbus_assert (!dbus_signature_validate (sig, NULL));
475 sig = DBUS_STRUCT_END_CHAR_AS_STRING
476 DBUS_STRUCT_BEGIN_CHAR_AS_STRING;
477 _dbus_assert (!dbus_signature_validate (sig, NULL));
479 sig = DBUS_STRUCT_BEGIN_CHAR_AS_STRING
480 DBUS_TYPE_BOOLEAN_AS_STRING;
481 _dbus_assert (!dbus_signature_validate (sig, NULL));
485 _dbus_assert_not_reached ("out of memory");
492 /** @} */ /* end of DBusSignature group */