294 lines
12 KiB
C
294 lines
12 KiB
C
#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
|