#include "dbus-internals.h"
#include "dbus-test.h"
+/**
+ * Implementation details of #DBusSignatureIter, all fields are private
+ */
typedef struct
{
- const char *pos;
- unsigned int finished : 1;
- unsigned int in_array : 1;
+ const char *pos; /**< current position in the signature string */
+ unsigned int finished : 1; /**< true if we are at the end iter */
+ unsigned int in_array : 1; /**< true if we are a subiterator pointing to an array's element type */
} DBusSignatureRealIter;
+/** macro that checks whether a typecode is a container type */
+#define TYPE_IS_CONTAINER(typecode) \
+ ((typecode) == DBUS_TYPE_STRUCT || \
+ (typecode) == DBUS_TYPE_DICT_ENTRY || \
+ (typecode) == DBUS_TYPE_VARIANT || \
+ (typecode) == DBUS_TYPE_ARRAY)
+
+
/**
- * @addtogroup DBusSignature
+ * @defgroup DBusSignature Type signature parsing
+ * @ingroup DBus
+ * @brief Parsing D-Bus type signatures
* @{
*/
* character such as '(' for a structure, the corresponding type for
* the container will be returned, e.g. DBUS_TYPE_STRUCT, not '('.
* In this case, you should initialize a sub-iterator with
- * dbus_signature_iter_recurse to parse the container type.
+ * dbus_signature_iter_recurse() to parse the container type.
*
* @param iter pointer to an iterator
- * @returns current type (e.g. DBUS_TYPE_STRING, DBUS_TYPE_ARRAY)
+ * @returns current type (e.g. #DBUS_TYPE_STRING, #DBUS_TYPE_ARRAY)
*/
int
dbus_signature_iter_get_current_type (const DBusSignatureIter *iter)
}
/**
+ * Returns the signature of the single complete type starting at the
+ * given iterator.
+ *
+ * For example, if the iterator is pointing at the start of "(ii)ii"
+ * (which is "a struct of two ints, followed by an int, followed by an
+ * int"), then "(ii)" would be returned. If the iterator is pointing at
+ * one of the "i" then just that "i" would be returned.
+ *
+ * @param iter pointer to an iterator
+ * @returns current signature; or #NULL if no memory. Should be freed with dbus_free()
+ */
+char *
+dbus_signature_iter_get_signature (const DBusSignatureIter *iter)
+{
+ DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
+ DBusString str;
+ char *ret;
+ int pos;
+
+ if (!_dbus_string_init (&str))
+ return NULL;
+
+ pos = 0;
+ _dbus_type_signature_next (real_iter->pos, &pos);
+
+ if (!_dbus_string_append_len (&str, real_iter->pos, pos))
+ return NULL;
+ if (!_dbus_string_steal_data (&str, &ret))
+ ret = NULL;
+ _dbus_string_free (&str);
+
+ return ret;
+}
+
+/**
* Convenience function for returning the element type of an array;
* This function allows you to avoid initializing a sub-iterator and
* getting its current type.
*
- * It is an error to invoke this function if the current type of the
- * iterator is not DBUS_TYPE_ARRAY.
+ * Undefined behavior results if you invoke this function when the
+ * current type of the iterator is not #DBUS_TYPE_ARRAY.
*
* @param iter pointer to an iterator
* @returns current array element type
{
DBusSignatureRealIter *real_iter = (DBusSignatureRealIter *) iter;
- _dbus_retur(dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY);
+ _dbus_return_val_if_fail (dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID);
return _dbus_first_type_in_signature_c_str (real_iter->pos, 1);
}
/**
* Skip to the next value on this "level". e.g. the next field in a
- * struct, the next value in an array. Returns FALSE at the end of the
+ * struct, the next value in an array. Returns #FALSE at the end of the
* current container.
*
* @param iter the iterator
}
/**
- * Initialize a new iterator pointing to the first type current
- * container. It's an error to call this if the current type is a
- * non-container (i.e. if dbus_type_is_container returns FALSE).
+ * Initialize a new iterator pointing to the first type in the current
+ * container.
+ *
+ * The results are undefined when calling this if the current type is
+ * a non-container (i.e. if dbus_type_is_container() returns #FALSE
+ * for the result of dbus_signature_iter_get_current_type()).
*
* @param iter the current interator
* @param subiter an iterator to initialize pointing to the first child
_dbus_return_if_fail (dbus_type_is_container (dbus_signature_iter_get_current_type (iter)));
*real_sub_iter = *real_iter;
+ real_sub_iter->in_array = FALSE;
real_sub_iter->pos++;
- if (dbus_signature_iter_get_current_type (subiter) == DBUS_TYPE_ARRAY)
+ if (dbus_signature_iter_get_current_type (iter) == DBUS_TYPE_ARRAY)
real_sub_iter->in_array = TRUE;
}
/**
- * Check a type signature for validity.
+ * Check a type signature for validity. Remember that #NULL can always
+ * be passed instead of a DBusError*, if you don't care about having
+ * an error name and message.
*
* @param signature a potentially invalid type signature
- * @error error return
- * @returns TRUE iif signature is valid
+ * @param error error return
+ * @returns #TRUE if signature is valid or #FALSE if an error is set
*/
dbus_bool_t
dbus_signature_validate (const char *signature,
}
/**
- * Check that a type signature is both valid and contains exactly
- * one complete type.
+ * Check that a type signature is both valid and contains exactly one
+ * complete type. "One complete type" means a single basic type,
+ * array, struct, or dictionary, though the struct or array may be
+ * arbitrarily recursive and complex. More than one complete type
+ * would mean for example "ii" or two integers in sequence.
*
* @param signature a potentially invalid type signature
- * @error error return
- * @returns TRUE iif signature is valid and has exactly one complete type
+ * @param error error return
+ * @returns #TRUE if signature is valid and has exactly one complete type
*/
dbus_bool_t
dbus_signature_validate_single (const char *signature,
return FALSE;
}
-/** macro that checks whether a typecode is a container type */
-#define TYPE_IS_CONTAINER(typecode) \
- ((typecode) == DBUS_TYPE_STRUCT || \
- (typecode) == DBUS_TYPE_DICT_ENTRY || \
- (typecode) == DBUS_TYPE_VARIANT || \
- (typecode) == DBUS_TYPE_ARRAY)
-
/**
* A "container type" can contain basic types, or nested
* container types. #DBUS_TYPE_INVALID is not a container type.
+ *
* This function will crash if passed a typecode that isn't
* in dbus-protocol.h
*
}
/**
- * A "basic type" is a somewhat arbitrary concept, but the intent
- * is to include those types that are fully-specified by a single
- * typecode, with no additional type information or nested
- * values. So all numbers and strings are basic types and
- * structs, arrays, and variants are not basic types.
- * #DBUS_TYPE_INVALID is not a basic type.
+ * A "basic type" is a somewhat arbitrary concept, but the intent is
+ * to include those types that are fully-specified by a single
+ * typecode, with no additional type information or nested values. So
+ * all numbers and strings are basic types and structs, arrays, and
+ * variants are not basic types. #DBUS_TYPE_INVALID is not a basic
+ * type.
*
* This function will crash if passed a typecode that isn't
- * in dbus-protocol.h
+ * in dbus-protocol.h
*
* @returns #TRUE if type is basic
*/
return !(typecode == DBUS_TYPE_INVALID || TYPE_IS_CONTAINER (typecode));
}
+/**
+ * Tells you whether values of this type can change length if you set
+ * them to some other value. For this purpose, you assume that the
+ * first byte of the old and new value would be in the same location,
+ * so alignment padding is not a factor.
+ *
+ * This function is useful to determine whether
+ * dbus_message_iter_get_fixed_array() may be used.
+ *
+ * Some structs are fixed-size (if they contain only fixed-size types)
+ * but struct is not considered a fixed type for purposes of this
+ * function.
+ *
+ * This function will crash if passed a typecode that isn't
+ * in dbus-protocol.h
+ *
+ * @returns #FALSE if the type can occupy different lengths
+ */
+dbus_bool_t
+dbus_type_is_fixed (int typecode)
+{
+ /* only reasonable (non-line-noise) typecodes are allowed */
+ _dbus_return_val_if_fail (_dbus_type_is_valid (typecode) || typecode == DBUS_TYPE_INVALID,
+ FALSE);
+
+ switch (typecode)
+ {
+ case DBUS_TYPE_BYTE:
+ case DBUS_TYPE_BOOLEAN:
+ case DBUS_TYPE_INT16:
+ case DBUS_TYPE_UINT16:
+ case DBUS_TYPE_INT32:
+ case DBUS_TYPE_UINT32:
+ case DBUS_TYPE_INT64:
+ case DBUS_TYPE_UINT64:
+ case DBUS_TYPE_DOUBLE:
+ return TRUE;
+ default:
+ return FALSE;
+ }
+}
+
+/** @} */ /* end of DBusSignature group */
#ifdef DBUS_BUILD_TESTS
DBusSignatureIter subsubiter;
DBusSignatureIter subsubsubiter;
const char *sig;
+ dbus_bool_t boolres;
_dbus_assert (sizeof (DBusSignatureIter) >= sizeof (DBusSignatureRealIter));
_dbus_assert (dbus_signature_validate (sig, NULL));
dbus_signature_iter_init (&iter, sig);
_dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRING);
- _dbus_assert (dbus_signature_iter_next (&iter));
+ boolres = dbus_signature_iter_next (&iter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_BYTE);
sig = DBUS_TYPE_UINT16_AS_STRING
_dbus_assert (dbus_signature_validate (sig, NULL));
dbus_signature_iter_init (&iter, sig);
_dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
- _dbus_assert (dbus_signature_iter_next (&iter));
+ boolres = dbus_signature_iter_next (&iter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
dbus_signature_iter_recurse (&iter, &subiter);
_dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRING);
- _dbus_assert (dbus_signature_iter_next (&subiter));
+ boolres = dbus_signature_iter_next (&subiter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
- _dbus_assert (dbus_signature_iter_next (&subiter));
+ boolres = dbus_signature_iter_next (&subiter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_VARIANT);
- _dbus_assert (dbus_signature_iter_next (&subiter));
+ boolres = dbus_signature_iter_next (&subiter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_DOUBLE);
sig = DBUS_TYPE_UINT16_AS_STRING
_dbus_assert (dbus_signature_validate (sig, NULL));
dbus_signature_iter_init (&iter, sig);
_dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_UINT16);
- _dbus_assert (dbus_signature_iter_next (&iter));
+ boolres = dbus_signature_iter_next (&iter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_STRUCT);
dbus_signature_iter_recurse (&iter, &subiter);
_dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_UINT32);
- _dbus_assert (dbus_signature_iter_next (&subiter));
+ boolres = dbus_signature_iter_next (&subiter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_BYTE);
- _dbus_assert (dbus_signature_iter_next (&subiter));
+ boolres = dbus_signature_iter_next (&subiter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_ARRAY);
_dbus_assert (dbus_signature_iter_get_element_type (&subiter) == DBUS_TYPE_ARRAY);
dbus_signature_iter_recurse (&subsubiter, &subsubsubiter);
_dbus_assert (dbus_signature_iter_get_current_type (&subsubsubiter) == DBUS_TYPE_DOUBLE);
- _dbus_assert (dbus_signature_iter_next (&subiter));
+ boolres = dbus_signature_iter_next (&subiter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&subiter) == DBUS_TYPE_STRUCT);
dbus_signature_iter_recurse (&subiter, &subsubiter);
_dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_BYTE);
dbus_signature_iter_recurse (&iter, &subiter);
dbus_signature_iter_recurse (&subiter, &subsubiter);
_dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_INT16);
- _dbus_assert (dbus_signature_iter_next (&subsubiter));
+ boolres = dbus_signature_iter_next (&subsubiter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&subsubiter) == DBUS_TYPE_STRING);
- _dbus_assert (!dbus_signature_iter_next (&subsubiter));
+ boolres = dbus_signature_iter_next (&subsubiter);
+ _dbus_assert (!boolres);
- _dbus_assert (dbus_signature_iter_next (&iter));
+ boolres = dbus_signature_iter_next (&iter);
+ _dbus_assert (boolres);
_dbus_assert (dbus_signature_iter_get_current_type (&iter) == DBUS_TYPE_VARIANT);
- _dbus_assert (!dbus_signature_iter_next (&iter));
+ boolres = dbus_signature_iter_next (&iter);
+ _dbus_assert (!boolres);
sig = DBUS_TYPE_DICT_ENTRY_AS_STRING;
_dbus_assert (!dbus_signature_validate (sig, NULL));
#endif
-/** @} */ /* end of DBusSignature group */
-