/**
* @typedef EDBus_Object
*
- * Represents a object path already attach with bus name or unique id.
+ * Represents an object path already attached with bus name or unique id.
*/
typedef struct _EDBus_Object EDBus_Object;
/**
* @typedef EDBus_Proxy
*
- * Represents a interface of a object path.
+ * Represents an interface of an object path.
*/
typedef struct _EDBus_Proxy EDBus_Proxy;
/**
* @typedef EDBus_Message
*
- * Represents the way of how the data is send and received in DBus.
+ * Represents the way data is sent and received in DBus.
*/
typedef struct _EDBus_Message EDBus_Message;
/**
/**
* @typedef EDBus_Pending
*
- * Represents a message that was been sent but has not yet reached its
+ * Represents a message that has been sent but has not yet reached its
* destination.
*/
typedef struct _EDBus_Pending EDBus_Pending;
EAPI EDBus_Connection *edbus_connection_ref(EDBus_Connection *conn) EINA_ARG_NONNULL(1);
/**
- * @brief Decrement object reference count.
+ * @brief Decrement connection reference count.
*
* If reference count reaches 0, the connection to bus will be dropped and all
* its children will be invalidated.
*
* @param conn The connection object to add the callback to.
* @param cb callback to be called
- * @param data passed to callback
+ * @param data data passed to callback
*/
EAPI void edbus_connection_cb_free_add(EDBus_Connection *conn, EDBus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2);
/**
* @brief Get data stored in connection.
*
- * @param conn connection where data are stored
- * @param key that identify data
+ * @param conn connection where data is stored
+ * @param key key that identifies data
*
* @return pointer to data if found otherwise NULL
*/
/**
* @brief Del data stored in connection.
*
- * @param conn connection where data are stored
- * @param key that identify data
+ * @param conn connection where data is stored
+ * @param key that identifies data
*
* @return pointer to data if found otherwise NULL
*/
typedef void (*EDBus_Connection_Event_Cb)(void *data, EDBus_Connection *conn, void *event_info);
/**
- * @brief Add a callback function to be called when occurs a event of the
+ * @brief Add a callback function to be called when an event occurs of the
* type passed.
*/
EAPI void edbus_connection_event_callback_add(EDBus_Connection *conn, EDBus_Connection_Event_Type type, EDBus_Connection_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3);
/**
* @brief Send a message.
*
- * @param conn the connection where the message will be send
- * @param msg message that will be send
+ * @param conn the connection where the message will be sent
+ * @param msg message that will be sent
* @param cb if msg is a method call a callback should be passed
- * to be execute when response arrive
+ * to be executed when a response arrives
* @param cb_data data passed to callback
- * @param timeout timeout in milliseconds, -1 to default internal value or
+ * @param timeout timeout in milliseconds, -1 to use default internal value or
* EDBUS_TIMEOUT_INFINITE for no timeout
*/
EAPI EDBus_Pending *edbus_connection_send(EDBus_Connection *conn, EDBus_Message *msg, EDBus_Message_Cb cb, const void *cb_data, double timeout) EINA_ARG_NONNULL(1, 2);
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 your children's.
+ * If reference == 0 message will be freed and all its children.
*/
EAPI void edbus_message_unref(EDBus_Message *msg) EINA_ARG_NONNULL(1);
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 must have
- * a pointer to store his value, in case of complex type a
- * EDBus_Message_Iter will be need.
+ * @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 need.
*/
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 must have
- * a pointer to store his value, in case of complex type a
- * EDBus_Message_Iter will be need.
+ * @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 support basic type from complex type use
+ * This function only supports basic type, for complex types use
* edbus_message_iter_* functions.
*/
EAPI Eina_Bool edbus_message_arguments_set(EDBus_Message *msg, const char *signature, ...) EINA_ARG_NONNULL(1, 2);
/**
* @brief Set data to EDBus_Message.
*
- * This function only support basic type from complex type use
+ * This function only supports basic types, for complex types use
* edbus_message_iter_* functions.
*/
EAPI Eina_Bool edbus_message_arguments_vset(EDBus_Message *msg, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2);
* @{
*/
/**
- * @brief Get a object of the following bus and path.
+ * @brief Get an object of the given bus and path.
*
* @param conn connection where object belongs
- * @param bus name of bus or unique-id of who listen for calls of this object
+ * @param bus name of bus or unique-id of who listens for calls of this object
* @param path object path of this object
*/
EAPI EDBus_Object *edbus_object_get(EDBus_Connection *conn, const char *bus, const char *path) EINA_ARG_NONNULL(1, 2, 3) EINA_WARN_UNUSED_RESULT;
EAPI EDBus_Object *edbus_object_ref(EDBus_Object *obj) EINA_ARG_NONNULL(1);
/**
* @brief Decrease object reference.
- * If reference == 0 object will be freed and all your children's.
+ * If reference == 0 object will be freed and all its children.
*/
EAPI void edbus_object_unref(EDBus_Object *obj) EINA_ARG_NONNULL(1);
/**
* @brief Add a callback function to be called when object will be freed.
*
- * @param obj object that you want to know when it will be free
- * @param cb callback that will be execute
+ * @param obj object that you want to monitor
+ * @param cb callback that will be executed
* @param data passed to callback
*/
EAPI void edbus_object_cb_free_add(EDBus_Object *obj, EDBus_Free_Cb cb, const void *data) EINA_ARG_NONNULL(1, 2);
typedef void (*EDBus_Object_Event_Cb)(void *data, EDBus_Object *obj, void *event_info);
/**
- * @brief Add a callback function to be called when occurs a event of the
- * type passed.
+ * @brief Add a callback function to be called when an event of the specified
+ * type occurs.
*/
EAPI void edbus_object_event_callback_add(EDBus_Object *obj, EDBus_Object_Event_Type type, EDBus_Object_Event_Cb cb, const void *cb_data) EINA_ARG_NONNULL(1, 3);
/**
/**
* @brief Send a message.
*
- * @param obj the msg will be send in connection that obj belongs
- * @param msg message that will be send
+ * @param obj the msg will be sent in connection to this object
+ * @param msg message that will be sent
* @param cb if msg is a method call a callback should be passed
- * to be execute when response arrive
+ * to be executed when a response arrives
* @param cb_data data passed to callback
* @param timeout timeout in milliseconds, -1 to default internal value or
* EDBUS_TIMEOUT_INFINITE for no timeout
EAPI EDBus_Proxy *edbus_proxy_ref(EDBus_Proxy *proxy) EINA_ARG_NONNULL(1);
/**
* @brief Decrease proxy reference.
- * If reference == 0 proxy will be freed and all your children's.
+ * If reference == 0 proxy will be freed and all your children.
*/
EAPI void edbus_proxy_unref(EDBus_Proxy *proxy) EINA_ARG_NONNULL(1);
} EDBus_Signal;
/**
- * @brief Register a interface on the passed path and connection.
+ * @brief Register an interface in the given path and connection.
*
* @param conn where the interface should listen
* @param path object path
EAPI EDBus_Service_Interface *edbus_service_interface_register(EDBus_Connection *conn, const char *path, const char *interface, const EDBus_Method methods[], const EDBus_Signal signals[]);
/**
* @brief Unregister a interface.
- * If this is the last interface of object path, the object path will be
- * remove too.
+ * If this is the last interface of the object path, the object path will be
+ * removed too.
*/
EAPI void edbus_service_interface_unregister(EDBus_Service_Interface *iface);
/**
* @brief Create signal message.
* Each signal handler have a internal id, the first signal handler of
* interface is = 0 the second = 1 and go on.
- * This function is used when signal have complex types.
+ * This function is used when the signal has complex types.
*
* @param iface interface of the signal
* @param signal_id id of signal
*/
EAPI Eina_Bool edbus_service_signal_send(EDBus_Service_Interface *iface, EDBus_Message *signal_msg) EINA_ARG_NONNULL(1, 2);
/**
- * @brief Store data at object path, this data can be get from all interfaces
+ * @brief Store data at object path, this data can be obtained from all interfaces
* of the same object.
*
* @param iface interface that belong to the object path where data will
/**
* @brief Get data stored in object path.
*
- * @param iface interface that belong to the object path where data are stored
+ * @param iface interface that belongs to the object path where data are stored
* @param key that identify data
*
* @return pointer to data if found otherwise NULL
/**
* @brief Del data stored in object path.
*
- * @param iface interface that belong to the object path where data are stored
+ * @param iface interface that belongs to the object path where data are stored
* @param key that identify data
*
* @return pointer to data if found otherwise NULL
EAPI void edbus_signal_handler_unref(EDBus_Signal_Handler *handler) EINA_ARG_NONNULL(1);
/**
* @brief Decrease signal handler reference like edbus_signal_handler_unref()
- * but if reference > 0 this signal handler will stop listen signals. In other
- * words will be canceled but memory will not be freed.
+ * but if reference > 0 this signal handler will stop listening to signals. In other
+ * words it will be canceled but memory will not be freed.
*/
EAPI void edbus_signal_handler_del(EDBus_Signal_Handler *handler) EINA_ARG_NONNULL(1);
/**
* With this extra arguments this signal handler callback only will be called
* when Banshee is started.
*
- * @note For now is only supported argX.
+ * @note For now only argX is supported.
*
* @param sh signal handler
* @param ... variadic of key and value and must be ended with a NULL
*
- * @note To information:
+ * @note For more information:
* http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing-match-rules
*/
EAPI Eina_Bool edbus_signal_handler_match_extra_set(EDBus_Signal_Handler *sh, ...) EINA_ARG_NONNULL(1) EINA_SENTINEL;
projects / platform / upstream / efl.git / commitdiff