#ifndef EDBUS_MESSAGE_H
#define EDBUS_MESSAGE_H 1

/**
 * @defgroup EDBus_Message Message
 * @ingroup EDBus
 *
 * @{
 */

/**
 * @brief Constructs a new message to invoke a method on a remote object.
 *
 * @param dest bus name or unique id of the remote applications
 * @param path object path
 * @param iface interface name
 * @param method name of method that will be called
 *
 * @return a new EDBus_Message, free with edbus_message_unref()
 */
EAPI EDBus_Message        *edbus_message_method_call_new(const char *dest, const char *path, const char *iface, const char *method) EINA_ARG_NONNULL(1, 2, 3, 4) EINA_WARN_UNUSED_RESULT EINA_MALLOC;

/**
 * @brief Increase message reference.
 */
EAPI EDBus_Message        *edbus_message_ref(EDBus_Message *msg) EINA_ARG_NONNULL(1);

/**
 * @brief Decrease message reference.
 * If reference == 0 message will be freed and all its children.
 */
EAPI void                  edbus_message_unref(EDBus_Message *msg) EINA_ARG_NONNULL(1);

EAPI const char           *edbus_message_path_get(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
EAPI const char           *edbus_message_interface_get(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
EAPI const char           *edbus_message_member_get(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
EAPI const char           *edbus_message_destination_get(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
EAPI const char           *edbus_message_sender_get(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
EAPI const char           *edbus_message_signature_get(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Creates a new message that is an error reply to another message.
 *
 * @param reply the message we're replying to
 * @param error_name the error name
 * @param error_msg the error message string
 *
 * @return new EDBus_Message, free with edbus_message_unref()
 */
EAPI EDBus_Message        *edbus_message_error_new(const EDBus_Message *reply, const char *error_name, const char *error_msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Constructs a message that is a reply to a method call.
 *
 * @param msg the message we're replying to
 *
 * @return new EDBus_Message, free with edbus_message_unref()
 */
EAPI EDBus_Message        *edbus_message_method_return_new(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;


/**
 * @brief If EDBus_Message is a message error return EINA_TRUE and fills
 * name and text if their pointers is not null.
 */
EAPI Eina_Bool             edbus_message_error_get(const EDBus_Message *msg, const char **name, const char **text) EINA_ARG_NONNULL(1);

/**
 * @brief Get data from EDBus_Message. For each complete type we must have
 * a pointer to store its value. In case of complex type EDBus_Message_Iter
 * needs to be used.
 */
EAPI Eina_Bool             edbus_message_arguments_get(const EDBus_Message *msg, const char *signature, ...) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Get data from EDBus_Message. For each complete type we must have
 * a pointer to store its value, in case of complex type
 * EDBus_Message_Iter needs to be used.
 */
EAPI Eina_Bool             edbus_message_arguments_vget(const EDBus_Message *msg, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Set data to EDBus_Message.
 *
 * This function only supports basic type, for complex types use
 * edbus_message_iter_* functions.
 */
EAPI Eina_Bool             edbus_message_arguments_append(EDBus_Message *msg, const char *signature, ...) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Set data to EDBus_Message.
 *
 * This function only supports basic types, for complex types use
 * edbus_message_iter_* functions.
 */
EAPI Eina_Bool             edbus_message_arguments_vappend(EDBus_Message *msg, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2);

/**
 * @defgroup EDBus_Message_Iter Iterator
 * @{
 */

/**
 * @brief Create and append a typed iterator to another iterator.
 *
 * After append data to returned iterator it must be closed calling
 * edbus_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.
 *
 * @param iter parent of the new iterator
 * @param type of iterator (e.g struct, dict, variant or array)
 * @param contained_signature signature of what iterator will store
 *
 * @return the new iterator
 */
EAPI EDBus_Message_Iter *edbus_message_iter_container_new(EDBus_Message_Iter *iter, int type, const char* contained_signature) EINA_ARG_NONNULL(1, 3) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Append a basic type into an EDBus_Iterator.
 */
EAPI Eina_Bool               edbus_message_iter_basic_append(EDBus_Message_Iter *iter, int type, ...) EINA_ARG_NONNULL(1, 3);

/**
 * @brief Append an argument into an EDBus_Message_Iter. For each complete type
 * you need to provide the correspondent value. In case of complex types you
 * need to provide an EDBus_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 edbus_message_iter_container_new(), fill the array,
 * close it with edbus_message_iter_container_close() and then do the same for
 * the second array.
 *
 * @param iter iterator in which data will be appended
 * @param signature signature of the contained data
 * @param ... values for each complete type
 *
 * @see edbus_message_iter_container_new()
 * @see edbus_message_iter_container_close()
 *
 * @note This function doesn't support variant, use
 * edbus_message_iter_container_new() instead to create the variant, fill
 * with data and close it.
 */
EAPI Eina_Bool               edbus_message_iter_arguments_append(EDBus_Message_Iter *iter, const char *signature, ...) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Set data to EDBus_Message_Iter. For each complete in signature
 * you need pass the value, in case of complex type a pointer to be allocated a
 * EDBus_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
 * edbus_message_iter_container_new() fill array with data and close then
 * you could open the second array with edbus_message_iter_container_new().
 *
 * @param iter iterator
 * @param signature of data
 * @param ap va_list with the values
 *
 * @note This function don't support variant, use instead
 * edbus_message_iter_container_new() to create the variant fill
 * data and close it.
 */
EAPI Eina_Bool               edbus_message_iter_arguments_vappend(EDBus_Message_Iter *iter, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2, 3);

/**
 * @brief Closes a container-typed value appended to the message.
 *
 * @param iter parent of the sub-iterator
 * @param sub the iterator that will be closed
 *
 * @return EINA_FALSE if iterator was already close or if not enough memory
 */
EAPI Eina_Bool               edbus_message_iter_container_close(EDBus_Message_Iter *iter, EDBus_Message_Iter *sub) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Get the main EDBus_Message_Iter from the EDBus_Message.
 */
EAPI EDBus_Message_Iter *edbus_message_iter_get(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Get a basic type from EDBus_Iterator.
 */
EAPI void                    edbus_message_iter_basic_get(EDBus_Message_Iter *iter, void *value) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Returns the current signature of a message iterator.
 *
 * @note The returned string must be freed.
 */
EAPI char                   *edbus_message_iter_signature_get(EDBus_Message_Iter *iter) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;

/**
 * @brief Moves the iterator to the next field, if any.
 * @param iter iterator
 *
 * @return if iterator was reach to end return EINA_FALSE
 */
EAPI Eina_Bool               edbus_message_iter_next(EDBus_Message_Iter *iter) EINA_ARG_NONNULL(1);

/**
 * @brief Get a complete type from EDBus_Message_Iter if is not at the end
 * of iterator and move to next field.
 * Useful to iterate over arrays.
 *
 * @param iter iterator
 * @param type of the next completed type in Iterator
 * @param ... pointer of where data will be stored
 *
 * @param if iterator was reach to end or if type different of the type that
 * iterator points return EINA_FALSE
 *
 */
EAPI Eina_Bool               edbus_message_iter_get_and_next(EDBus_Message_Iter *iter, char type, ...) EINA_ARG_NONNULL(1, 2, 3);

/**
 * @brief 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 EDBUS_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.
 */
EAPI Eina_Bool edbus_message_iter_fixed_array_get(EDBus_Message_Iter *iter, int signature, void *value, int *n_elements) EINA_ARG_NONNULL(1, 3, 4);

/**
 * @brief Get data from EDBus_Message_Iter, for each complete type must have
 * a pointer to store his value, in case of complex type a
 * EDBus_Message_Iter will be need.
 *
 * @param iter iterator
 * @param signature of the complete data types on interator
 * @param ... pointers of where data will be stored
 *
 * @return EINA_FALSE if signature different from signature in iterator
 */
EAPI Eina_Bool               edbus_message_iter_arguments_get(EDBus_Message_Iter *iter, const char *signature, ...) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Get data from EDBus_Message_Iter, for each complete type must have
 * a pointer to store his value, in case of complex type a
 * EDBus_Message_Iter will be need.
 *
 * @param iter iterator
 * @param signature of the complete data types on interator
 * @param ap va_list of the pointers of where data will be stored
 *
 * @return EINA_FALSE if signature different from signature in iterator
 */
EAPI Eina_Bool               edbus_message_iter_arguments_vget(EDBus_Message_Iter *iter, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2);

/**
 * @brief Manually delete the iterator.
 *
 * Iterators are usually bound to the life of @ref EDBus_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.
 *
 * @param iter the iterator to be deleted.
 */
EAPI void                  edbus_message_iter_del(EDBus_Message_Iter *iter) EINA_ARG_NONNULL(1);

/**
 * @}
 */

#include "edbus_message_helper.h"
#include "edbus_message_eina_value.h"

/**
 * @}
 */
#endif