Merge branch 'dbus-1.2'
[platform/upstream/dbus.git] / dbus / dbus-signature.c
1 /* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
2 /* dbus-signature.c  Routines for reading recursive type signatures
3  *
4  * Copyright (C) 2005 Red Hat, Inc.
5  *
6  * Licensed under the Academic Free License version 2.1
7  *
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.
12  *
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.
17  *
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
21  *
22  */
23
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"
29
30 /**
31  * Implementation details of #DBusSignatureIter, all fields are private
32  */
33 typedef struct
34
35   const char *pos;           /**< current position in the signature string */
36   unsigned int finished : 1; /**< true if we are at the end iter */
37   unsigned int in_array : 1; /**< true if we are a subiterator pointing to an array's element type */
38 } DBusSignatureRealIter;
39
40 /** macro that checks whether a typecode is a container type */
41 #define TYPE_IS_CONTAINER(typecode)             \
42     ((typecode) == DBUS_TYPE_STRUCT ||          \
43      (typecode) == DBUS_TYPE_DICT_ENTRY ||      \
44      (typecode) == DBUS_TYPE_VARIANT ||         \
45      (typecode) == DBUS_TYPE_ARRAY)
46
47
48 /**
49  * @defgroup DBusSignature Type signature parsing
50  * @ingroup  DBus
51  * @brief Parsing D-Bus type signatures
52  * @{
53  */
54
55 /**
56  * Initializes a #DBusSignatureIter for reading a type signature.  This
57  * function is not safe to use on invalid signatures; be sure to
58  * validate potentially invalid signatures with dbus_signature_validate
59  * before using this function.
60  *
61  * @param iter pointer to an iterator to initialize
62  * @param signature the type signature
63  */
64 void
65 dbus_signature_iter_init (DBusSignatureIter *iter,
66                           const char        *signature)
67 {
68   DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
69
70   real_iter->pos = signature;
71   real_iter->finished = FALSE;
72   real_iter->in_array = FALSE;
73 }
74
75 /**
76  * Returns the current type pointed to by the iterator.
77  * If the iterator is pointing at a type code such as 's', then
78  * it will be returned directly.
79  *
80  * However, when the parser encounters a container type start
81  * character such as '(' for a structure, the corresponding type for
82  * the container will be returned, e.g.  DBUS_TYPE_STRUCT, not '('.
83  * In this case, you should initialize a sub-iterator with
84  * dbus_signature_iter_recurse() to parse the container type.
85  *
86  * @param iter pointer to an iterator 
87  * @returns current type (e.g. #DBUS_TYPE_STRING, #DBUS_TYPE_ARRAY)
88  */
89 int
90 dbus_signature_iter_get_current_type (const DBusSignatureIter *iter)
91 {
92   DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
93
94   return _dbus_first_type_in_signature_c_str (real_iter->pos, 0);
95 }
96
97 /**
98  * Returns the signature of the single complete type starting at the
99  * given iterator.
100  *
101  * For example, if the iterator is pointing at the start of "(ii)ii"
102  * (which is "a struct of two ints, followed by an int, followed by an
103  * int"), then "(ii)" would be returned. If the iterator is pointing at
104  * one of the "i" then just that "i" would be returned.
105  *
106  * @param iter pointer to an iterator 
107  * @returns current signature; or #NULL if no memory.  Should be freed with dbus_free()
108  */
109 char *
110 dbus_signature_iter_get_signature (const DBusSignatureIter *iter)
111 {
112   DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
113   DBusString str;
114   char *ret;
115   int pos;
116   
117   if (!_dbus_string_init (&str))
118     return NULL;
119
120   pos = 0;
121   _dbus_type_signature_next (real_iter->pos, &pos);
122
123   if (!_dbus_string_append_len (&str, real_iter->pos, pos))
124     return NULL;
125   if (!_dbus_string_steal_data (&str, &ret))
126     ret = NULL;
127   _dbus_string_free (&str);
128
129   return ret; 
130 }
131
132 /**
133  * Convenience function for returning the element type of an array;
134  * This function allows you to avoid initializing a sub-iterator and
135  * getting its current type.
136  *
137  * Undefined behavior results if you invoke this function when the
138  * current type of the iterator is not #DBUS_TYPE_ARRAY.
139  *
140  * @param iter pointer to an iterator 
141  * @returns current array element type
142  */
143 int
144 dbus_signature_iter_get_element_type (const DBusSignatureIter *iter)
145 {
146   DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
147
148   _dbus_return_val_if_fail (dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
149
150   return _dbus_first_type_in_signature_c_str (real_iter->pos, 1);
151 }
152
153 /**
154  * Skip to the next value on this "level". e.g. the next field in a
155  * struct, the next value in an array. Returns #FALSE at the end of the
156  * current container.
157  *
158  * @param iter the iterator
159  * @returns FALSE if nothing more to read at or below this level
160  */
161 dbus_bool_t
162 dbus_signature_iter_next (DBusSignatureIter *iter)
163 {
164   DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
165
166   if (real_iter->finished)
167     return FALSE;
168   else
169     {
170       int pos;
171
172       if (real_iter->in_array)
173         {
174           real_iter->finished = TRUE;
175           return FALSE;
176         }
177
178       pos = 0;
179       _dbus_type_signature_next (real_iter->pos, &pos);
180       real_iter->pos += pos;
181
182       if (*real_iter->pos == DBUS_STRUCT_END_CHAR
183           || *real_iter->pos == DBUS_DICT_ENTRY_END_CHAR)
184         {
185           real_iter->finished = TRUE;
186           return FALSE;
187         }
188
189       return *real_iter->pos != DBUS_TYPE_INVALID;
190     }
191 }
192
193 /**
194  * Initialize a new iterator pointing to the first type in the current
195  * container.
196  * 
197  * The results are undefined when calling this if the current type is
198  * a non-container (i.e. if dbus_type_is_container() returns #FALSE
199  * for the result of dbus_signature_iter_get_current_type()).
200  *
201  * @param iter the current interator
202  * @param subiter an iterator to initialize pointing to the first child
203  */
204 void
205 dbus_signature_iter_recurse (const DBusSignatureIter *iter,
206                              DBusSignatureIter       *subiter)
207 {
208   DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
209   DBusSignatureRealIter *real_sub_iter = (DBusSignatureRealIter *) subiter;
210
211   _dbus_return_if_fail (dbus_type_is_container (dbus_signature_iter_get_current_type (iter)));
212
213   *real_sub_iter = *real_iter;
214   real_sub_iter->in_array = FALSE;
215   real_sub_iter->pos++;
216
217   if (dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY)
218     real_sub_iter->in_array = TRUE;
219 }
220
221 /**
222  * Check a type signature for validity. Remember that #NULL can always
223  * be passed instead of a DBusError*, if you don't care about having
224  * an error name and message.
225  *
226  * @param signature a potentially invalid type signature
227  * @param error error return
228  * @returns #TRUE if signature is valid or #FALSE if an error is set
229  */
230 dbus_bool_t
231 dbus_signature_validate (const char       *signature,
232                          DBusError        *error)
233                          
234 {
235   DBusString str;
236   DBusValidity reason;
237
238   _dbus_string_init_const (&str, signature);
239   reason = _dbus_validate_signature_with_reason (&str, 0, _dbus_string_get_length (&str));
240
241   if (reason == DBUS_VALID)
242     return TRUE;
243   else
244     {
245       dbus_set_error (error, DBUS_ERROR_INVALID_SIGNATURE, _dbus_validity_to_error_message (reason));
246       return FALSE;
247     }
248 }
249
250 /**
251  * Check that a type signature is both valid and contains exactly one
252  * complete type. "One complete type" means a single basic type,
253  * array, struct, or dictionary, though the struct or array may be
254  * arbitrarily recursive and complex. More than one complete type
255  * would mean for example "ii" or two integers in sequence.
256  *
257  * @param signature a potentially invalid type signature
258  * @param error error return
259  * @returns #TRUE if signature is valid and has exactly one complete type
260  */
261 dbus_bool_t
262 dbus_signature_validate_single (const char       *signature,
263                                 DBusError        *error)
264 {
265   DBusSignatureIter iter;
266
267   if (!dbus_signature_validate (signature, error))
268     return FALSE;
269
270   dbus_signature_iter_init (&iter, signature);
271   if (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_INVALID)
272     goto lose;
273   if (!dbus_signature_iter_next (&iter))
274     return TRUE;
275  lose:
276   dbus_set_error (error, DBUS_ERROR_INVALID_SIGNATURE, "Exactly one complete type required in signature");
277   return FALSE;
278 }
279
280 /**
281  * A "container type" can contain basic types, or nested
282  * container types. #DBUS_TYPE_INVALID is not a container type.
283  *
284  * This function will crash if passed a typecode that isn't
285  * in dbus-protocol.h
286  *
287  * @returns #TRUE if type is a container
288  */
289 dbus_bool_t
290 dbus_type_is_container (int typecode)
291 {
292   /* only reasonable (non-line-noise) typecodes are allowed */
293   _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
294                             FALSE);
295   return TYPE_IS_CONTAINER (typecode);
296 }
297
298 /**
299  * A "basic type" is a somewhat arbitrary concept, but the intent is
300  * to include those types that are fully-specified by a single
301  * typecode, with no additional type information or nested values. So
302  * all numbers and strings are basic types and structs, arrays, and
303  * variants are not basic types.  #DBUS_TYPE_INVALID is not a basic
304  * type.
305  *
306  * This function will crash if passed a typecode that isn't
307  * in dbus-protocol.h 
308  *
309  * @returns #TRUE if type is basic
310  */
311 dbus_bool_t
312 dbus_type_is_basic (int typecode)
313 {
314   /* only reasonable (non-line-noise) typecodes are allowed */
315   _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
316                             FALSE);
317
318   /* everything that isn't invalid or a container */
319   return !(typecode == DBUS_TYPE_INVALID || TYPE_IS_CONTAINER (typecode));
320 }
321
322 /**
323  * Tells you whether values of this type can change length if you set
324  * them to some other value. For this purpose, you assume that the
325  * first byte of the old and new value would be in the same location,
326  * so alignment padding is not a factor.
327  *
328  * This function is useful to determine whether
329  * dbus_message_iter_get_fixed_array() may be used.
330  *
331  * Some structs are fixed-size (if they contain only fixed-size types)
332  * but struct is not considered a fixed type for purposes of this
333  * function.
334  *
335  * This function will crash if passed a typecode that isn't
336  * in dbus-protocol.h
337  * 
338  * @returns #FALSE if the type can occupy different lengths
339  */
340 dbus_bool_t
341 dbus_type_is_fixed (int typecode)
342 {
343   /* only reasonable (non-line-noise) typecodes are allowed */
344   _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
345                             FALSE);
346   
347   switch (typecode)
348     {
349     case DBUS_TYPE_BYTE:
350     case DBUS_TYPE_BOOLEAN:
351     case DBUS_TYPE_INT16:
352     case DBUS_TYPE_UINT16:
353     case DBUS_TYPE_INT32:
354     case DBUS_TYPE_UINT32:
355     case DBUS_TYPE_INT64:
356     case DBUS_TYPE_UINT64:
357     case DBUS_TYPE_DOUBLE:
358     case DBUS_TYPE_UNIX_FD:
359       return TRUE;
360     default:
361       return FALSE;
362     }
363 }
364
365 /** @} */ /* end of DBusSignature group */
366
367 #ifdef DBUS_BUILD_TESTS
368
369 /**
370  * @ingroup DBusSignatureInternals
371  * Unit test for DBusSignature.
372  *
373  * @returns #TRUE on success.
374  */
375 dbus_bool_t
376 _dbus_signature_test (void)
377 {
378   DBusSignatureIter iter;
379   DBusSignatureIter subiter;
380   DBusSignatureIter subsubiter;
381   DBusSignatureIter subsubsubiter;
382   const char *sig;
383   dbus_bool_t boolres;
384
385   _dbus_assert (sizeof (DBusSignatureIter) >= sizeof (DBusSignatureRealIter));
386
387   sig = "";
388   _dbus_assert (dbus_signature_validate (sig, NULL));
389   _dbus_assert (!dbus_signature_validate_single (sig, NULL));
390   dbus_signature_iter_init (&iter, sig);
391   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_INVALID);
392
393   sig = DBUS_TYPE_STRING_AS_STRING;
394   _dbus_assert (dbus_signature_validate (sig, NULL));
395   _dbus_assert (dbus_signature_validate_single (sig, NULL));
396   dbus_signature_iter_init (&iter, sig);
397   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRING);
398
399   sig = DBUS_TYPE_STRING_AS_STRING DBUS_TYPE_BYTE_AS_STRING;
400   _dbus_assert (dbus_signature_validate (sig, NULL));
401   dbus_signature_iter_init (&iter, sig);
402   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRING);
403   boolres = dbus_signature_iter_next (&iter);
404   _dbus_assert (boolres);
405   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_BYTE);
406
407   sig = DBUS_TYPE_UINT16_AS_STRING
408     DBUS_STRUCT_BEGIN_CHAR_AS_STRING
409     DBUS_TYPE_STRING_AS_STRING
410     DBUS_TYPE_UINT32_AS_STRING
411     DBUS_TYPE_VARIANT_AS_STRING
412     DBUS_TYPE_DOUBLE_AS_STRING
413     DBUS_STRUCT_END_CHAR_AS_STRING;
414   _dbus_assert (dbus_signature_validate (sig, NULL));
415   dbus_signature_iter_init (&iter, sig);
416   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
417   boolres = dbus_signature_iter_next (&iter);
418   _dbus_assert (boolres);
419   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
420   dbus_signature_iter_recurse (&iter, &subiter);
421   _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRING);
422   boolres = dbus_signature_iter_next (&subiter);
423   _dbus_assert (boolres);
424   _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
425   boolres = dbus_signature_iter_next (&subiter);
426   _dbus_assert (boolres);
427   _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_VARIANT);
428   boolres = dbus_signature_iter_next (&subiter);
429   _dbus_assert (boolres);
430   _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_DOUBLE);
431
432   sig = DBUS_TYPE_UINT16_AS_STRING
433     DBUS_STRUCT_BEGIN_CHAR_AS_STRING
434     DBUS_TYPE_UINT32_AS_STRING
435     DBUS_TYPE_BYTE_AS_STRING
436     DBUS_TYPE_ARRAY_AS_STRING
437     DBUS_TYPE_ARRAY_AS_STRING
438     DBUS_TYPE_DOUBLE_AS_STRING
439     DBUS_STRUCT_BEGIN_CHAR_AS_STRING
440     DBUS_TYPE_BYTE_AS_STRING
441     DBUS_STRUCT_END_CHAR_AS_STRING
442     DBUS_STRUCT_END_CHAR_AS_STRING;
443   _dbus_assert (dbus_signature_validate (sig, NULL));
444   dbus_signature_iter_init (&iter, sig);
445   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
446   boolres = dbus_signature_iter_next (&iter);
447   _dbus_assert (boolres);
448   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
449   dbus_signature_iter_recurse (&iter, &subiter);
450   _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
451   boolres = dbus_signature_iter_next (&subiter);
452   _dbus_assert (boolres);
453   _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_BYTE);
454   boolres = dbus_signature_iter_next (&subiter);
455   _dbus_assert (boolres);
456   _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_ARRAY);
457   _dbus_assert (dbus_signature_iter_get_element_type (&subiter) == DBUS_TYPE_ARRAY);
458
459   dbus_signature_iter_recurse (&subiter, &subsubiter);
460   _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_ARRAY);
461   _dbus_assert (dbus_signature_iter_get_element_type (&subsubiter) == DBUS_TYPE_DOUBLE);
462
463   dbus_signature_iter_recurse (&subsubiter, &subsubsubiter);
464   _dbus_assert (dbus_signature_iter_get_current_type (&subsubsubiter) == DBUS_TYPE_DOUBLE);
465   boolres = dbus_signature_iter_next (&subiter);
466   _dbus_assert (boolres);
467   _dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRUCT);
468   dbus_signature_iter_recurse (&subiter, &subsubiter);
469   _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_BYTE);
470
471   sig = DBUS_TYPE_ARRAY_AS_STRING
472     DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
473     DBUS_TYPE_INT16_AS_STRING
474     DBUS_TYPE_STRING_AS_STRING
475     DBUS_DICT_ENTRY_END_CHAR_AS_STRING
476     DBUS_TYPE_VARIANT_AS_STRING;
477   _dbus_assert (dbus_signature_validate (sig, NULL));
478   _dbus_assert (!dbus_signature_validate_single (sig, NULL));
479   dbus_signature_iter_init (&iter, sig);
480   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_ARRAY);
481   _dbus_assert (dbus_signature_iter_get_element_type (&iter) == DBUS_TYPE_DICT_ENTRY);
482
483   dbus_signature_iter_recurse (&iter, &subiter);
484   dbus_signature_iter_recurse (&subiter, &subsubiter);
485   _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_INT16);
486   boolres = dbus_signature_iter_next (&subsubiter);
487   _dbus_assert (boolres);
488   _dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_STRING);
489   boolres = dbus_signature_iter_next (&subsubiter);
490   _dbus_assert (!boolres);
491
492   boolres = dbus_signature_iter_next (&iter);
493   _dbus_assert (boolres);
494   _dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_VARIANT);
495   boolres = dbus_signature_iter_next (&iter);
496   _dbus_assert (!boolres);
497
498   sig = DBUS_TYPE_DICT_ENTRY_AS_STRING;
499   _dbus_assert (!dbus_signature_validate (sig, NULL));
500
501   sig = DBUS_TYPE_ARRAY_AS_STRING;
502   _dbus_assert (!dbus_signature_validate (sig, NULL));
503
504   sig = DBUS_TYPE_UINT32_AS_STRING
505     DBUS_TYPE_ARRAY_AS_STRING;
506   _dbus_assert (!dbus_signature_validate (sig, NULL));
507
508   sig = DBUS_TYPE_ARRAY_AS_STRING
509     DBUS_TYPE_DICT_ENTRY_AS_STRING;
510   _dbus_assert (!dbus_signature_validate (sig, NULL));
511
512   sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING;
513   _dbus_assert (!dbus_signature_validate (sig, NULL));
514
515   sig = DBUS_DICT_ENTRY_END_CHAR_AS_STRING;
516   _dbus_assert (!dbus_signature_validate (sig, NULL));
517
518   sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
519     DBUS_TYPE_INT32_AS_STRING;
520   _dbus_assert (!dbus_signature_validate (sig, NULL));
521
522   sig = DBUS_DICT_ENTRY_BEGIN_CHAR_AS_STRING
523     DBUS_TYPE_INT32_AS_STRING
524     DBUS_TYPE_STRING_AS_STRING;
525   _dbus_assert (!dbus_signature_validate (sig, NULL));
526
527   sig = DBUS_STRUCT_END_CHAR_AS_STRING
528     DBUS_STRUCT_BEGIN_CHAR_AS_STRING;
529   _dbus_assert (!dbus_signature_validate (sig, NULL));
530
531   sig = DBUS_STRUCT_BEGIN_CHAR_AS_STRING
532     DBUS_TYPE_BOOLEAN_AS_STRING;
533   _dbus_assert (!dbus_signature_validate (sig, NULL));
534   return TRUE;
535 #if 0
536  oom:
537   _dbus_assert_not_reached ("out of memory");
538   return FALSE;
539 #endif
540 }
541
542 #endif
543