D-Bus: Type signature parsing

D-Bus 1.14.0

Data Structures | Functions
Type signature parsing
D-Bus low-level public API

Parsing D-Bus type signatures. More...

## Data Structures
struct | DBusSignatureIter
| DBusSignatureIter struct; contains no public fields. More...

## Functions
void | dbus_signature_iter_init (DBusSignatureIter *iter, const char *signature)
| Initializes a DBusSignatureIter for reading a type signature. More...
int | dbus_signature_iter_get_current_type (const DBusSignatureIter *iter)
| Returns the current type pointed to by the iterator. More...
char * | dbus_signature_iter_get_signature (const DBusSignatureIter *iter)
| Returns the signature of the single complete type starting at the given iterator. More...
int | dbus_signature_iter_get_element_type (const DBusSignatureIter *iter)
| 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. More...
dbus_bool_t | dbus_signature_iter_next (DBusSignatureIter *iter)
| Skip to the next value on this "level". More...
void | dbus_signature_iter_recurse (const DBusSignatureIter *iter, DBusSignatureIter *subiter)
| Initialize a new iterator pointing to the first type in the current container. More...
dbus_bool_t | dbus_signature_validate (const char *signature, DBusError *error)
| Check a type signature for validity. More...
dbus_bool_t | dbus_signature_validate_single (const char *signature, DBusError *error)
| Check that a type signature is both valid and contains exactly one complete type. More...
dbus_bool_t | dbus_type_is_container (int typecode)
| A "container type" can contain basic types, or nested container types. More...
dbus_bool_t | dbus_type_is_basic (int typecode)
| 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. More...
dbus_bool_t | dbus_type_is_fixed (int typecode)
| Tells you whether values of this type can change length if you set them to some other value. More...
dbus_bool_t | dbus_type_is_valid (int typecode)
| Return TRUE if the argument is a valid typecode. More...

## Detailed Description

Parsing D-Bus type signatures.

## Function Documentation

## ◆ dbus_signature_iter_get_current_type()

DBUS_EXPORT int dbus_signature_iter_get_current_type | ( | const DBusSignatureIter * | iter | ) |

Returns the current type pointed to by the iterator.

If the iterator is pointing at a type code such as 's', then it will be returned directly.

However, when the parser encounters a container type start 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.

Parameters

  iter | pointer to an iterator

Returns
  current type (e.g. DBUS_TYPE_STRING, DBUS_TYPE_ARRAY)

Definition at line 95 of file dbus-signature.c.

References _dbus_first_type_in_signature_c_str(), and DBusSignatureRealIter::pos.

Referenced by dbus_signature_iter_get_element_type(), dbus_signature_iter_recurse(), and dbus_signature_validate_single().

## ◆ dbus_signature_iter_get_element_type()

DBUS_EXPORT int dbus_signature_iter_get_element_type | ( | const DBusSignatureIter * | iter | ) |

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.

Undefined behavior results if you invoke this function when the current type of the iterator is not DBUS_TYPE_ARRAY.

Parameters

  iter | pointer to an iterator

Returns
  current array element type

Definition at line 149 of file dbus-signature.c.

References _dbus_first_type_in_signature_c_str(), dbus_signature_iter_get_current_type(), DBUS_TYPE_ARRAY, DBUS_TYPE_INVALID, and DBusSignatureRealIter::pos.

## ◆ dbus_signature_iter_get_signature()

DBUS_EXPORT char * dbus_signature_iter_get_signature | ( | 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.

Parameters

  iter | pointer to an iterator

Returns
  current signature; or NULL if no memory. Should be freed with dbus_free()

Definition at line 115 of file dbus-signature.c.

References _dbus_string_append_len(), _dbus_string_free(), _dbus_string_init(), _dbus_string_steal_data(), _dbus_type_signature_next(), NULL, and DBusSignatureRealIter::pos.

## ◆ dbus_signature_iter_init()

DBUS_EXPORT void dbus_signature_iter_init | ( | DBusSignatureIter * | iter,
|  | const char * | signature
| ) |  |

Initializes a DBusSignatureIter for reading a type signature.

This function is not safe to use on invalid signatures; be sure to validate potentially invalid signatures with dbus_signature_validate before using this function.

Parameters

  iter | pointer to an iterator to initialize
  signature | the type signature

Definition at line 70 of file dbus-signature.c.

References FALSE, DBusSignatureRealIter::finished, DBusSignatureRealIter::in_array, and DBusSignatureRealIter::pos.

Referenced by dbus_signature_validate_single().

## ◆ dbus_signature_iter_next()

DBUS_EXPORT dbus_bool_t dbus_signature_iter_next | ( | DBusSignatureIter * | iter | ) |

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 current container.

Parameters

  iter | the iterator

Returns
  FALSE if nothing more to read at or below this level

Definition at line 167 of file dbus-signature.c.

References _dbus_type_signature_next(), DBUS_DICT_ENTRY_END_CHAR, DBUS_STRUCT_END_CHAR, DBUS_TYPE_INVALID, FALSE, DBusSignatureRealIter::finished, DBusSignatureRealIter::in_array, DBusSignatureRealIter::pos, and TRUE.

Referenced by dbus_signature_validate_single().

## ◆ dbus_signature_iter_recurse()

DBUS_EXPORT void dbus_signature_iter_recurse | ( | const DBusSignatureIter * | iter,
|  | DBusSignatureIter * | subiter
| ) |  |

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()).

Parameters

  iter | the current interator
  subiter | an iterator to initialize pointing to the first child

Definition at line 210 of file dbus-signature.c.

References dbus_signature_iter_get_current_type(), DBUS_TYPE_ARRAY, dbus_type_is_container(), FALSE, DBusSignatureRealIter::in_array, DBusSignatureRealIter::pos, and TRUE.

## ◆ dbus_signature_validate()

DBUS_EXPORT dbus_bool_t dbus_signature_validate | ( | const char * | signature,
|  | DBusError * | error
| ) |  |

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.

Parameters

  signature | a potentially invalid type signature
  error | error return

Returns
  TRUE if signature is valid or FALSE if an error is set

Definition at line 236 of file dbus-signature.c.

References _dbus_string_init_const(), _dbus_validate_signature_with_reason(), DBUS_ERROR_INVALID_SIGNATURE, dbus_set_error(), DBUS_VALID, and TRUE.

Referenced by dbus_signature_validate_single().

## ◆ dbus_signature_validate_single()

DBUS_EXPORT dbus_bool_t dbus_signature_validate_single | ( | const char * | signature,
|  | DBusError * | error
| ) |  |

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.

Parameters

  signature | a potentially invalid type signature
  error | error return

Returns
  TRUE if signature is valid and has exactly one complete type

Definition at line 268 of file dbus-signature.c.

References DBUS_ERROR_INVALID_SIGNATURE, dbus_set_error(), dbus_signature_iter_get_current_type(), dbus_signature_iter_init(), dbus_signature_iter_next(), dbus_signature_validate(), DBUS_TYPE_INVALID, FALSE, and TRUE.

## ◆ dbus_type_is_basic()

DBUS_EXPORT dbus_bool_t dbus_type_is_basic | ( | int | typecode | ) |

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.

It is an error to pass an invalid type-code, other than DBUS_TYPE_INVALID, to this function. The valid type-codes are defined by dbus-protocol.h and can be checked with dbus_type_is_valid().

Parameters

  typecode | either a valid type-code or DBUS_TYPE_INVALID

Returns
  TRUE if type is basic

Definition at line 322 of file dbus-signature.c.

References DBUS_TYPE_INVALID, dbus_type_is_valid(), and FALSE.

Referenced by _dbus_marshal_read_basic(), _dbus_marshal_write_basic(), _dbus_message_iter_get_args_valist(), _dbus_type_reader_set_basic(), and dbus_message_append_args_valist().

## ◆ dbus_type_is_container()

DBUS_EXPORT dbus_bool_t dbus_type_is_container | ( | int | typecode | ) |

A "container type" can contain basic types, or nested container types.

DBUS_TYPE_INVALID is not a container type.

It is an error to pass an invalid type-code, other than DBUS_TYPE_INVALID, to this function. The valid type-codes are defined by dbus-protocol.h and can be checked with dbus_type_is_valid().

Parameters

  typecode | either a valid type-code or DBUS_TYPE_INVALID

Returns
  TRUE if type is a container

Definition at line 298 of file dbus-signature.c.

References DBUS_TYPE_INVALID, dbus_type_is_valid(), and FALSE.

Referenced by dbus_signature_iter_recurse().

## ◆ dbus_type_is_fixed()

DBUS_EXPORT dbus_bool_t dbus_type_is_fixed | ( | int | 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.

It is an error to pass an invalid type-code, other than DBUS_TYPE_INVALID, to this function. The valid type-codes are defined by dbus-protocol.h and can be checked with dbus_type_is_valid().

Parameters

  typecode | either a valid type-code or DBUS_TYPE_INVALID

Returns
  FALSE if the type can occupy different lengths

Definition at line 353 of file dbus-signature.c.

References DBUS_TYPE_BOOLEAN, DBUS_TYPE_BYTE, DBUS_TYPE_DOUBLE, DBUS_TYPE_INT16, DBUS_TYPE_INT32, DBUS_TYPE_INT64, DBUS_TYPE_INVALID, dbus_type_is_valid(), DBUS_TYPE_UINT16, DBUS_TYPE_UINT32, DBUS_TYPE_UINT64, DBUS_TYPE_UNIX_FD, FALSE, and TRUE.

Referenced by _dbus_marshal_write_fixed_multi(), _dbus_message_iter_get_args_valist(), _dbus_type_reader_set_basic(), _dbus_type_writer_write_fixed_multi(), dbus_message_append_args_valist(), dbus_message_iter_get_element_count(), and dbus_message_iter_get_fixed_array().

## ◆ dbus_type_is_valid()

DBUS_EXPORT dbus_bool_t dbus_type_is_valid | ( | int | typecode | ) |

Return TRUE if the argument is a valid typecode.

DBUS_TYPE_INVALID surprisingly enough is not considered valid, and random unknown bytes aren't either. This function is safe with untrusted data.

Parameters

  typecode | a potential type-code

Returns
  TRUE if valid

Definition at line 387 of file dbus-signature.c.

References DBUS_TYPE_ARRAY, DBUS_TYPE_BOOLEAN, DBUS_TYPE_BYTE, DBUS_TYPE_DICT_ENTRY, DBUS_TYPE_DOUBLE, DBUS_TYPE_INT16, DBUS_TYPE_INT32, DBUS_TYPE_INT64, DBUS_TYPE_OBJECT_PATH, DBUS_TYPE_SIGNATURE, DBUS_TYPE_STRING, DBUS_TYPE_STRUCT, DBUS_TYPE_UINT16, DBUS_TYPE_UINT32, DBUS_TYPE_UINT64, DBUS_TYPE_UNIX_FD, DBUS_TYPE_VARIANT, FALSE, and TRUE.

Referenced by dbus_connection_can_send_type(), dbus_type_is_basic(), dbus_type_is_container(), and dbus_type_is_fixed().