summaryrefslogtreecommitdiff
path: root/src
diff options
context:
space:
mode:
authorLucas De Marchi <lucas.demarchi@profusion.mobi>2013-01-03 15:06:39 +0000
committerLucas De Marchi <lucas.demarchi@profusion.mobi>2013-01-03 15:06:39 +0000
commitc1d576dcc7fa9485de73f60a7d886e100ad9e147 (patch)
treeef25ccf65058592f797dbc9af76a7504f2a09dcb /src
parentaf8c81634fe96b599c0c30d4677630fe24f6a26d (diff)
edbus: improve doc of edbus_message_* functions
SVN revision: 82081
Diffstat (limited to 'src')
-rw-r--r--src/lib/edbus/edbus_message.c3
-rw-r--r--src/lib/edbus/edbus_message.h108
2 files changed, 76 insertions, 35 deletions
diff --git a/src/lib/edbus/edbus_message.c b/src/lib/edbus/edbus_message.c
index d6694e94ba..5d14efb64b 100644
--- a/src/lib/edbus/edbus_message.c
+++ b/src/lib/edbus/edbus_message.c
@@ -803,9 +803,6 @@ edbus_message_iter_del(EDBus_Message_Iter *iter)
803 _message_iterator_free(iter); 803 _message_iterator_free(iter);
804} 804}
805 805
806/* TODO: proper doc
807 * Return the *reply* to @msg, i.e. @msg is the message we are replying to.
808 */
809EAPI EDBus_Message * 806EAPI EDBus_Message *
810edbus_message_error_new(const EDBus_Message *msg, const char *error_name, const char *error_msg) 807edbus_message_error_new(const EDBus_Message *msg, const char *error_name, const char *error_msg)
811{ 808{
diff --git a/src/lib/edbus/edbus_message.h b/src/lib/edbus/edbus_message.h
index ac4d251aa1..000e2dd268 100644
--- a/src/lib/edbus/edbus_message.h
+++ b/src/lib/edbus/edbus_message.h
@@ -9,25 +9,15 @@
9 */ 9 */
10 10
11/** 11/**
12 * @brief Constructs a new message to invoke a method on a remote object.
13 *
14 * @param dest bus name or unique id of the remote applications
15 * @param path object path
16 * @param iface interface name
17 * @param method name of method that will be called
18 *
19 * @return a new EDBus_Message, free with edbus_message_unref()
20 */
21EAPI 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;
22
23/**
24 * @brief Increase message reference. 12 * @brief Increase message reference.
25 */ 13 */
26EAPI EDBus_Message *edbus_message_ref(EDBus_Message *msg) EINA_ARG_NONNULL(1); 14EAPI EDBus_Message *edbus_message_ref(EDBus_Message *msg) EINA_ARG_NONNULL(1);
27 15
28/** 16/**
29 * @brief Decrease message reference. 17 * @brief Decrease message reference.
30 * If reference == 0 message will be freed and all its children. 18 *
19 * When refcount reaches zero the message and all its resources will be
20 * freed.
31 */ 21 */
32EAPI void edbus_message_unref(EDBus_Message *msg) EINA_ARG_NONNULL(1); 22EAPI void edbus_message_unref(EDBus_Message *msg) EINA_ARG_NONNULL(1);
33 23
@@ -39,18 +29,30 @@ EAPI const char *edbus_message_sender_get(const EDBus_Message *msg) EI
39EAPI const char *edbus_message_signature_get(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 29EAPI const char *edbus_message_signature_get(const EDBus_Message *msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
40 30
41/** 31/**
42 * @brief Creates a new message that is an error reply to another message. 32 * @brief Create a new message to invoke a method on a remote object.
43 * 33 *
44 * @param reply the message we're replying to 34 * @param dest bus name or unique id of the remote application
35 * @param path object path
36 * @param iface interface name
37 * @param method name of the method to be called
38 *
39 * @return a new EDBus_Message, free with edbus_message_unref()
40 */
41EAPI 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;
42
43/**
44 * @brief Create a new message that is an error reply to another message.
45 *
46 * @param msg the message we're replying to
45 * @param error_name the error name 47 * @param error_name the error name
46 * @param error_msg the error message string 48 * @param error_msg the error message string
47 * 49 *
48 * @return new EDBus_Message, free with edbus_message_unref() 50 * @return a new EDBus_Message, free with edbus_message_unref()
49 */ 51 */
50EAPI 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; 52EAPI EDBus_Message *edbus_message_error_new(const EDBus_Message *msg, const char *error_name, const char *error_msg) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
51 53
52/** 54/**
53 * @brief Constructs a message that is a reply to a method call. 55 * @brief Create a message that is a reply to a method call.
54 * 56 *
55 * @param msg the message we're replying to 57 * @param msg the message we're replying to
56 * 58 *
@@ -60,38 +62,80 @@ EAPI EDBus_Message *edbus_message_method_return_new(const EDBus_Message *
60 62
61 63
62/** 64/**
63 * @brief If EDBus_Message is a message error return EINA_TRUE and fills 65 * @brief Get the error text and name from a EDBus_Message.
64 * name and text if their pointers is not null. 66 *
67 * If @param msg is an error message return EINA_TRUE and fill in the name and
68 * text of the error.
69 *
70 * @param msg The message containing the error
71 * @param name Variable in which to store the error name or @c NULL if it's not
72 * desired.
73 * @param text Variable in which to store the error text or @c NULL if it's not
74 * desired.
65 */ 75 */
66EAPI Eina_Bool edbus_message_error_get(const EDBus_Message *msg, const char **name, const char **text) EINA_ARG_NONNULL(1); 76EAPI Eina_Bool edbus_message_error_get(const EDBus_Message *msg, const char **name, const char **text) EINA_ARG_NONNULL(1);
67 77
68/** 78/**
69 * @brief Get data from EDBus_Message. For each complete type we must have 79 * @brief Get the arguments from an EDBus_Message
70 * a pointer to store its value. In case of complex type EDBus_Message_Iter 80 *
71 * needs to be used. 81 * Get the arguments of an EDBus_Message storing them in the locations pointed
82 * to by the pointer arguments that follow @param signature. Each pointer
83 * argument must be of a type that is appropriate for the correspondent complete
84 * type in @param signature. For complex types such as arrays, structs,
85 * dictionaries or variants, a pointer to EDBus_Message_Iter* must be provided.
86 *
87 * @param msg The message to get the arguments from.
88 * @param signature The signature of the arguments user is expecting to read
89 * from @param msg
90 * @param ... The pointers in which to store the message arguments
91 *
92 * @return EINA_TRUE if the arguments were read succesfully and stored in the
93 * respective pointer arguments.
72 */ 94 */
73EAPI Eina_Bool edbus_message_arguments_get(const EDBus_Message *msg, const char *signature, ...) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; 95EAPI Eina_Bool edbus_message_arguments_get(const EDBus_Message *msg, const char *signature, ...) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
74 96
75/** 97/**
76 * @brief Get data from EDBus_Message. For each complete type we must have 98 * @brief Get the arguments from an EDBus_Message using a va_list.
77 * a pointer to store its value, in case of complex type 99 *
78 * EDBus_Message_Iter needs to be used. 100 * @param msg The message to get the arguments from.
101 * @param signature The signature user is expecting to read from @param msg.
102 * @param ap The va_list containing the pointer arguments.
103 *
104 * @see edbus_message_arguments_get()
105 *
106 * @return EINA_TRUE if the arguments were read succesfully and stored in the
107 * respective pointer arguments.
79 */ 108 */
80EAPI 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; 109EAPI 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;
81 110
82/** 111/**
83 * @brief Set data to EDBus_Message. 112 * @brief Append arguments into an EDBus_Message
113 *
114 * Append arguments into an EDBus_Message according to the @param signature
115 * provided. For each complete type in @param signature, a value of the
116 * corresponding type must be provided.
84 * 117 *
85 * This function only supports basic type, for complex types use 118 * This function supports only basic types. For complex types use
86 * edbus_message_iter_* functions. 119 * edbus_message_iter_* family of functions.
120 *
121 * @param msg The message in which arguments are being appended.
122 * @param signature Signature of the arguments that are being appended.
123 * @param ... Values of each argument to append in @param msg.
124 *
125 * @return EINA_TRUE on success, EINA_FALSE otherwise.
87 */ 126 */
88EAPI Eina_Bool edbus_message_arguments_append(EDBus_Message *msg, const char *signature, ...) EINA_ARG_NONNULL(1, 2); 127EAPI Eina_Bool edbus_message_arguments_append(EDBus_Message *msg, const char *signature, ...) EINA_ARG_NONNULL(1, 2);
89 128
90/** 129/**
91 * @brief Set data to EDBus_Message. 130 * @brief Append arguments into an EDBus_Message using a va_list.
131 *
132 * @param msg The message in which arguments are being appended.
133 * @param signature Signature of the arguments that are being appended.
134 * @param ap The va_list containing the arguments to append.
135 *
136 * @see edbus_message_arguments_append().
92 * 137 *
93 * This function only supports basic types, for complex types use 138 * @return EINA_TRUE on success, EINA_FALSE otherwise.
94 * edbus_message_iter_* functions.
95 */ 139 */
96EAPI Eina_Bool edbus_message_arguments_vappend(EDBus_Message *msg, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2); 140EAPI Eina_Bool edbus_message_arguments_vappend(EDBus_Message *msg, const char *signature, va_list ap) EINA_ARG_NONNULL(1, 2);
97 141