Iterator
Eldbus » Message

## Functions

Eldbus_Message_Iter * | eldbus_message_iter_container_new (Eldbus_Message_Iter *iter, int type, const char *contained_signature)
| Create and append a typed iterator to another iterator.
Eina_Bool | eldbus_message_iter_basic_append (Eldbus_Message_Iter *iter, int type,...)
| Append a basic type into an Eldbus_Iterator.
Eina_Bool | eldbus_message_iter_arguments_append (Eldbus_Message_Iter *iter, const char *signature,...)
| Append an argument into an Eldbus_Message_Iter.
Eina_Bool | eldbus_message_iter_arguments_vappend (Eldbus_Message_Iter *iter, const char *signature, va_list ap)
| Set data to Eldbus_Message_Iter.
Eina_Bool | eldbus_message_iter_fixed_array_append (Eldbus_Message_Iter *iter, int type, const void *array, unsigned int size)
| Append a array of basic type with fixed size to Eldbus_Message_Iter.
Eina_Bool | eldbus_message_iter_container_close (Eldbus_Message_Iter *iter, Eldbus_Message_Iter *sub)
| Closes a container-typed value appended to the message.
Eldbus_Message_Iter * | eldbus_message_iter_get (const Eldbus_Message *msg)
| Get the main Eldbus_Message_Iter from the Eldbus_Message.
void | eldbus_message_iter_basic_get (Eldbus_Message_Iter *iter, void *value)
| Get a basic type from Eldbus_Iterator.
char * | eldbus_message_iter_signature_get (Eldbus_Message_Iter *iter)
| Returns the current signature of a message iterator.
Eina_Bool | eldbus_message_iter_next (Eldbus_Message_Iter *iter)
| Moves the iterator to the next field, if any.
Eina_Bool | eldbus_message_iter_get_and_next (Eldbus_Message_Iter *iter, char signature,...)
| Get a complete type from Eldbus_Message_Iter if is not at the end of iterator and move to next field.
Eina_Bool | eldbus_message_iter_fixed_array_get (Eldbus_Message_Iter *iter, int signature, void *value, int *n_elements)
| Reads a block of fixed-length values from the message iterator.
Eina_Bool | eldbus_message_iter_arguments_get (Eldbus_Message_Iter *iter, const char *signature,...)
| Get data from Eldbus_Message_Iter, for each complete type must have a pointer to store his value, in case of complex type a Eldbus_Message_Iter will be need.
Eina_Bool | eldbus_message_iter_arguments_vget (Eldbus_Message_Iter *iter, const char *signature, va_list ap)
| Get data from Eldbus_Message_Iter, for each complete type must have a pointer to store his value, in case of complex type a Eldbus_Message_Iter will be need.
void | eldbus_message_iter_del (Eldbus_Message_Iter *iter)
| Manually delete the iterator.

## Detailed Description

## Function Documentation

## eldbus_message_iter_container_new()

Eldbus_Message_Iter * eldbus_message_iter_container_new | ( | Eldbus_Message_Iter * | iter,
|  | int | type,
|  | const char * | contained_signature )

Create and append a typed iterator to another iterator.

After append data to returned iterator it must be closed calling eldbus_message_iter_container_close().

Container types are for example struct, variant, and array. For variants, the contained_signature should be the type of the single value inside the variant. For structs and dict entries, contained_signature should be NULL; it will be set to whatever types you write into the struct. For arrays, contained_signature should be the type of the array elements.

Parameters

  iter | parent of the new iterator
  type | of iterator (e.g struct, dict, variant or array)
  contained_signature | signature of what iterator will store

Returns
  the new iterator

References eina_inlist_append(), EINA_INLIST_GET, EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

Referenced by eldbus_proxy_property_set(), and eldbus_proxy_property_value_set().

## eldbus_message_iter_basic_append()

Eina_Bool eldbus_message_iter_basic_append | ( | Eldbus_Message_Iter * | iter,
|  | int | type,
|  |  | ... )

Append a basic type into an Eldbus_Iterator.

Parameters

  iter | The iterator in which basic type will be appended.
  type | The basic type that will be appended.
  ... | The values for the basic type.

Returns
  EINA_TRUE on success, else EINA_FALSE.

References EINA_FALSE, and EINA_SAFETY_ON_FALSE_RETURN_VAL.

Referenced by eldbus_proxy_property_set(), and eldbus_proxy_property_value_set().

## eldbus_message_iter_arguments_append()

Eina_Bool eldbus_message_iter_arguments_append | ( | Eldbus_Message_Iter * | iter,
|  | const char * | signature,
|  |  | ... )

Append an argument into an Eldbus_Message_Iter.

For each complete type you need to provide the correspondent value. In case of complex types you need to provide an Eldbus_Message_Iter** to be allocated and then filled in.

It's not possible to open two iterators at same iterator with this function. For example, to create a message with signature="aiai" you need to create the first container with eldbus_message_iter_container_new(), fill the array, close it with eldbus_message_iter_container_close() and then do the same for the second array.

Parameters

  iter | iterator in which data will be appended
  signature | signature of the contained data
  ... | values for each complete type

Returns
  EINA_TRUE on success, else EINA_FALSE

See also
  eldbus_message_iter_container_new()
  eldbus_message_iter_container_close()

Note
  This function doesn't support variant, use eldbus_message_iter_container_new() instead to create the variant, fill with data and close it.

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and eldbus_message_iter_arguments_vappend().

Referenced by ethumb_client_ethumb_setup().

## eldbus_message_iter_arguments_vappend()

Eina_Bool eldbus_message_iter_arguments_vappend | ( | Eldbus_Message_Iter * | iter,
|  | const char * | signature,
|  | va_list | ap )

Set data to Eldbus_Message_Iter.

For each complete in signature you need pass the value, in case of complex type a pointer to be allocated a Eldbus_Message_Iter that you need fill and close.

It's not possible open two iterators at same Iterator. Example: "aiai", to set this you need create and put the first array with eldbus_message_iter_container_new() fill array with data and close then you could open the second array with eldbus_message_iter_container_new().

Parameters

  iter | iterator
  signature | of data
  ap | va_list with the values

Returns
  EINA_TRUE on success, else EINA_FALSE

Note
  This function don't support variant, use instead eldbus_message_iter_container_new() to create the variant fill data and close it.

Referenced by eldbus_message_iter_arguments_append().

## eldbus_message_iter_fixed_array_append()

Eina_Bool eldbus_message_iter_fixed_array_append | ( | Eldbus_Message_Iter * | iter,
|  | int | type,
|  | const void * | array,
|  | unsigned int | size )

Append a array of basic type with fixed size to Eldbus_Message_Iter.

Parameters

  iter | iterator
  type | basic type that will be appended
  array | data to append
  size | of array

Returns
  EINA_TRUE on success, else EINA_FALSE

References EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## eldbus_message_iter_container_close()

Eina_Bool eldbus_message_iter_container_close | ( | Eldbus_Message_Iter * | iter,
|  | Eldbus_Message_Iter * | sub )

Closes a container-typed value appended to the message.

Parameters

  iter | parent of the sub-iterator
  sub | the iterator that will be closed

Returns
  EINA_FALSE if iterator was already close or if not enough memory

References EINA_FALSE, and EINA_SAFETY_ON_FALSE_RETURN_VAL.

Referenced by eldbus_proxy_property_set(), eldbus_proxy_property_value_set(), and ethumb_client_ethumb_setup().

## eldbus_message_iter_get()

Eldbus_Message_Iter * eldbus_message_iter_get | ( | const Eldbus_Message * | msg | ) |

Get the main Eldbus_Message_Iter from the Eldbus_Message.

Parameters

  msg | The message to get the iterator from.

Returns
  The iterator of the message.

References EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eldbus_message_from_eina_value(), eldbus_message_to_eina_value(), eldbus_proxy_property_set(), eldbus_proxy_property_value_set(), and ethumb_client_ethumb_setup().

## eldbus_message_iter_basic_get()

void eldbus_message_iter_basic_get | ( | Eldbus_Message_Iter * | iter,
|  | void * | value )

Get a basic type from Eldbus_Iterator.

Parameters

  iter | The iterator to get the basic type from.
  value | The basic type of the iterator.

References EINA_SAFETY_ON_TRUE_RETURN.

## eldbus_message_iter_signature_get()

char * eldbus_message_iter_signature_get | ( | Eldbus_Message_Iter * | iter | ) |

Returns the current signature of a message iterator.

Parameters

  iter | The iterator on which to query the signature.

Returns
  A string containing the message iterator signature.

Note
  The returned string must be freed.

Referenced by eldbus_message_iter_dict_iterate().

## eldbus_message_iter_next()

Eina_Bool eldbus_message_iter_next | ( | Eldbus_Message_Iter * | iter | ) |

Moves the iterator to the next field, if any.

Parameters

  iter | iterator

Returns
  if iterator was reach to end return EINA_FALSE

References EINA_FALSE, and EINA_SAFETY_ON_TRUE_RETURN_VAL.

## eldbus_message_iter_get_and_next()

Eina_Bool eldbus_message_iter_get_and_next | ( | Eldbus_Message_Iter * | iter,
|  | char | signature,
|  |  | ... )

Get a complete type from Eldbus_Message_Iter if is not at the end of iterator and move to next field.

Useful to iterate over arrays.

Parameters

  iter | iterator
  signature | of the next completed type in Iterator
  ... | pointer of where data will be stored

Returns
  if iterator was reach to end or if type different of the type that iterator points return EINA_FALSE

Get a complete type from Eldbus_Message_Iter if is not at the end of iterator and move to next field.

References EINA_FALSE, eina_inlist_append(), EINA_INLIST_GET, EINA_SAFETY_ON_TRUE_RETURN_VAL, and EINA_TRUE.

Referenced by efl_net_connman_access_point_update(), efl_net_connman_technology_new(), and eldbus_message_iter_dict_iterate().

## eldbus_message_iter_fixed_array_get()

Eina_Bool eldbus_message_iter_fixed_array_get | ( | Eldbus_Message_Iter * | iter,
|  | int | signature,
|  | void * | value,
|  | int * | n_elements )

Reads a block of fixed-length values from the message iterator.

Fixed-length values are those basic types that are not string-like, such as integers, bool, double. The returned block will be from the current position in the array until the end of the array.

There is one exception here: although ELDBUS_TYPE_UNIX_FD is considered a 'fixed' type arrays of this type may not be read with this function.

The value argument should be the address of a location to store the returned array. So for int32 it should be a "const dbus_int32_t**" The returned value is by reference and should not be freed.

Because the array is not copied, this function runs in constant time and is fast; it's much preferred over walking the entire array with an iterator.

Parameters

  iter | The message iterator
  signature |
  value |
  n_elements |

Returns
  EINA_TRUE on success, else EINA_FALSE.

References EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_SAFETY_ON_TRUE_RETURN_VAL, and EINA_TRUE.

## eldbus_message_iter_arguments_get()

Eina_Bool eldbus_message_iter_arguments_get | ( | Eldbus_Message_Iter * | iter,
|  | const char * | signature,
|  |  | ... )

Get data from Eldbus_Message_Iter, for each complete type must have a pointer to store his value, in case of complex type a Eldbus_Message_Iter will be need.

Parameters

  iter | iterator
  signature | of the complete data types on iterator
  ... | pointers of where data will be stored

Returns
  EINA_FALSE if signature different from signature in iterator

Referenced by eldbus_message_iter_dict_iterate().

## eldbus_message_iter_arguments_vget()

Eina_Bool eldbus_message_iter_arguments_vget | ( | Eldbus_Message_Iter * | iter,
|  | const char * | signature,
|  | va_list | ap )

Get data from Eldbus_Message_Iter, for each complete type must have a pointer to store his value, in case of complex type a Eldbus_Message_Iter will be need.

Parameters

  iter | iterator
  signature | of the complete data types on iterator
  ap | va_list of the pointers of where data will be stored

Returns
  EINA_FALSE if signature different from signature in iterator

## eldbus_message_iter_del()

void eldbus_message_iter_del | ( | Eldbus_Message_Iter * | iter | ) |

Manually delete the iterator.

Iterators are usually bound to the life of Message they were created from, being deleted automatically once the message is deleted.

However when dealing with huge arrays or dicts it may become a major memory impact to leave the unused iterators alive. By calling this function one states the iterator is not used anymore and can be deleted.

Parameters

  iter | the iterator to be deleted.