diff options
author | TheJackiMonster <thejackimonster@gmail.com> | 2021-08-09 17:58:34 +0200 |
---|---|---|
committer | TheJackiMonster <thejackimonster@gmail.com> | 2021-08-09 17:58:34 +0200 |
commit | 20986c3046f7cfc0d1c014cf1d6ee371b6ff5bbf (patch) | |
tree | b8373f3b8fc3d18f7f047865e513e1cea6030764 | |
parent | 2893686e2d29f9ff2e7c07aff1c1c93ee8f5734a (diff) | |
download | libgnunetchat-20986c3046f7cfc0d1c014cf1d6ee371b6ff5bbf.tar.gz libgnunetchat-20986c3046f7cfc0d1c014cf1d6ee371b6ff5bbf.zip |
Written doxygen documentation to the library header
Signed-off-by: TheJackiMonster <thejackimonster@gmail.com>
-rw-r--r-- | include/gnunet_chat_lib.h | 543 | ||||
-rw-r--r-- | src/gnunet_chat_lib.c | 6 |
2 files changed, 305 insertions, 244 deletions
diff --git a/include/gnunet_chat_lib.h b/include/gnunet_chat_lib.h index a920973..e061429 100644 --- a/include/gnunet_chat_lib.h +++ b/include/gnunet_chat_lib.h | |||
@@ -35,166 +35,169 @@ | |||
35 | #include <gnunet/gnunet_util_lib.h> | 35 | #include <gnunet/gnunet_util_lib.h> |
36 | 36 | ||
37 | /** | 37 | /** |
38 | * TODO | 38 | * Enum for the different kinds of messages. |
39 | */ | 39 | */ |
40 | enum GNUNET_CHAT_MessageKind | 40 | enum GNUNET_CHAT_MessageKind |
41 | { | 41 | { |
42 | /** | 42 | /** |
43 | * TODO | 43 | * The kind to inform that a contact has joined a chat. |
44 | */ | 44 | */ |
45 | GNUNET_CHAT_KIND_JOIN = 1, /**< GNUNET_CHAT_KIND_JOIN */ | 45 | GNUNET_CHAT_KIND_JOIN = 1, /**< GNUNET_CHAT_KIND_JOIN */ |
46 | 46 | ||
47 | /** | 47 | /** |
48 | * TODO | 48 | * The kind to inform that a contact has left a chat. |
49 | */ | 49 | */ |
50 | GNUNET_CHAT_KIND_LEAVE = 2, /**< GNUNET_CHAT_KIND_LEAVE */ | 50 | GNUNET_CHAT_KIND_LEAVE = 2, /**< GNUNET_CHAT_KIND_LEAVE */ |
51 | 51 | ||
52 | /** | 52 | /** |
53 | * TODO | 53 | * The kind to inform that a contact has changed. |
54 | */ | 54 | */ |
55 | GNUNET_CHAT_KIND_CONTACT = 3, /**< GNUNET_CHAT_KIND_CONTACT */ | 55 | GNUNET_CHAT_KIND_CONTACT = 3, /**< GNUNET_CHAT_KIND_CONTACT */ |
56 | 56 | ||
57 | /** | 57 | /** |
58 | * TODO | 58 | * The kind to describe an invitation to a different chat. |
59 | */ | 59 | */ |
60 | GNUNET_CHAT_KIND_INVITATION = 4, /**< GNUNET_CHAT_KIND_INVITATION */ | 60 | GNUNET_CHAT_KIND_INVITATION = 4, /**< GNUNET_CHAT_KIND_INVITATION */ |
61 | 61 | ||
62 | /** | 62 | /** |
63 | * TODO | 63 | * The kind to describe a text message. |
64 | */ | 64 | */ |
65 | GNUNET_CHAT_KIND_TEXT = 5, /**< GNUNET_CHAT_KIND_TEXT */ | 65 | GNUNET_CHAT_KIND_TEXT = 5, /**< GNUNET_CHAT_KIND_TEXT */ |
66 | 66 | ||
67 | /** | 67 | /** |
68 | * TODO | 68 | * The kind to describe a shared file. |
69 | */ | 69 | */ |
70 | GNUNET_CHAT_KIND_FILE = 6, /**< GNUNET_CHAT_KIND_FILE */ | 70 | GNUNET_CHAT_KIND_FILE = 6, /**< GNUNET_CHAT_KIND_FILE */ |
71 | 71 | ||
72 | /** | 72 | /** |
73 | * TODO | 73 | * The kind to inform about a deletion of a previous message. |
74 | */ | 74 | */ |
75 | GNUNET_CHAT_KIND_DELETION = 7, /**< GNUNET_CHAT_KIND_DELETION */ | 75 | GNUNET_CHAT_KIND_DELETION = 7, /**< GNUNET_CHAT_KIND_DELETION */ |
76 | 76 | ||
77 | /** | 77 | /** |
78 | * TODO | 78 | * An unknown kind of message. |
79 | */ | 79 | */ |
80 | GNUNET_CHAT_KIND_UNKNOWN = 0 /**< GNUNET_CHAT_KIND_UNKNOWN */ | 80 | GNUNET_CHAT_KIND_UNKNOWN = 0 /**< GNUNET_CHAT_KIND_UNKNOWN */ |
81 | }; | 81 | }; |
82 | 82 | ||
83 | /** | 83 | /** |
84 | * TODO | 84 | * Struct of a chat handle. |
85 | */ | 85 | */ |
86 | struct GNUNET_CHAT_Handle; | 86 | struct GNUNET_CHAT_Handle; |
87 | 87 | ||
88 | /** | 88 | /** |
89 | * TODO | 89 | * Struct of a chat contact. |
90 | */ | 90 | */ |
91 | struct GNUNET_CHAT_Contact; | 91 | struct GNUNET_CHAT_Contact; |
92 | 92 | ||
93 | /** | 93 | /** |
94 | * TODO | 94 | * Struct of a chat group. |
95 | */ | 95 | */ |
96 | struct GNUNET_CHAT_Group; | 96 | struct GNUNET_CHAT_Group; |
97 | 97 | ||
98 | /** | 98 | /** |
99 | * TODO | 99 | * Struct of a chat context. |
100 | */ | 100 | */ |
101 | struct GNUNET_CHAT_Context; | 101 | struct GNUNET_CHAT_Context; |
102 | 102 | ||
103 | /** | 103 | /** |
104 | * TODO | 104 | * Struct of a chat message. |
105 | */ | 105 | */ |
106 | struct GNUNET_CHAT_Message; | 106 | struct GNUNET_CHAT_Message; |
107 | 107 | ||
108 | /** | 108 | /** |
109 | * TODO | 109 | * Struct of a chat file. |
110 | */ | 110 | */ |
111 | struct GNUNET_CHAT_File; | 111 | struct GNUNET_CHAT_File; |
112 | 112 | ||
113 | /** | 113 | /** |
114 | * TODO | 114 | * Struct of a chat invitation. |
115 | */ | 115 | */ |
116 | struct GNUNET_CHAT_Invitation; | 116 | struct GNUNET_CHAT_Invitation; |
117 | 117 | ||
118 | /** | 118 | /** |
119 | * TODO | 119 | * Method called whenever an issue occurs regarding a certain chat context |
120 | * of a specific chat handle. | ||
120 | * | 121 | * |
121 | * @param cls | 122 | * @param[in/out] cls Closure from #GNUNET_CHAT_start |
122 | * @param handle | 123 | * @param[in/out] handle Chat handle |
123 | * @param context | 124 | * @param[in/out] context Chat context |
124 | * @param reason | 125 | * @param[in] reason Reason indicating the issue |
125 | */ | 126 | */ |
126 | typedef void | 127 | typedef void |
127 | (*GNUNET_CHAT_WarningCallback) (void *cls, struct GNUNET_CHAT_Handle *handle, | 128 | (*GNUNET_CHAT_WarningCallback) (void *cls, struct GNUNET_CHAT_Handle *handle, |
128 | struct GNUNET_CHAT_Context *context, int reason); | 129 | struct GNUNET_CHAT_Context *context, int reason); |
129 | 130 | ||
130 | /** | 131 | /** |
131 | * TODO | 132 | * Iterator over chat contacts of a specific chat handle. |
132 | * | 133 | * |
133 | * @param cls | 134 | * @param[in/out] cls Closure from #GNUNET_CHAT_iterate_contacts |
134 | * @param handle | 135 | * @param[in/out] handle Chat handle |
135 | * @param contact | 136 | * @param[in/out] contact Chat contact |
136 | * @return | 137 | * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. |
137 | */ | 138 | */ |
138 | typedef int | 139 | typedef int |
139 | (*GNUNET_CHAT_ContactCallback) (void *cls, struct GNUNET_CHAT_Handle *handle, | 140 | (*GNUNET_CHAT_ContactCallback) (void *cls, struct GNUNET_CHAT_Handle *handle, |
140 | struct GNUNET_CHAT_Contact *contact); | 141 | struct GNUNET_CHAT_Contact *contact); |
141 | 142 | ||
142 | /** | 143 | /** |
143 | * TODO | 144 | * Iterator over chat groups of a specific chat handle. |
144 | * | 145 | * |
145 | * @param cls | 146 | * @param[in/out] cls Closure from #GNUNET_CHAT_iterate_groups |
146 | * @param handle | 147 | * @param[in/out] handle Chat handle |
147 | * @param group | 148 | * @param[in/out] group Chat group |
148 | * @return | 149 | * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. |
149 | */ | 150 | */ |
150 | typedef int | 151 | typedef int |
151 | (*GNUNET_CHAT_GroupCallback) (void *cls, struct GNUNET_CHAT_Handle *handle, | 152 | (*GNUNET_CHAT_GroupCallback) (void *cls, struct GNUNET_CHAT_Handle *handle, |
152 | struct GNUNET_CHAT_Group *group); | 153 | struct GNUNET_CHAT_Group *group); |
153 | 154 | ||
154 | /** | 155 | /** |
155 | * TODO | 156 | * Iterator over chat contacts in a specific chat group. |
156 | * | 157 | * |
157 | * @param cls | 158 | * @param[in/out] cls Closure from #GNUNET_CHAT_group_iterate_contacts |
158 | * @param group | 159 | * @param[in/out] group Chat group |
159 | * @param contact | 160 | * @param[in/out] contact Chat contact |
160 | * @return | 161 | * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. |
161 | */ | 162 | */ |
162 | typedef int | 163 | typedef int |
163 | (*GNUNET_CHAT_GroupContactCallback) (void *cls, struct GNUNET_CHAT_Group *group, | 164 | (*GNUNET_CHAT_GroupContactCallback) (void *cls, struct GNUNET_CHAT_Group *group, |
164 | struct GNUNET_CHAT_Contact *contact); | 165 | struct GNUNET_CHAT_Contact *contact); |
165 | 166 | ||
166 | /** | 167 | /** |
167 | * TODO | 168 | * Iterator over chat messages in a specific chat context. |
168 | * | 169 | * |
169 | * @param cls | 170 | * @param[in/out] cls Closure from #GNUNET_CHAT_context_iterate_messages |
170 | * @param context | 171 | * @param[in/out] context Chat context |
171 | * @param message | 172 | * @param[in] message Chat message |
172 | * @return | 173 | * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. |
173 | */ | 174 | */ |
174 | typedef int | 175 | typedef int |
175 | (*GNUNET_CHAT_ContextMessageCallback) (void *cls, struct GNUNET_CHAT_Context *context, | 176 | (*GNUNET_CHAT_ContextMessageCallback) (void *cls, struct GNUNET_CHAT_Context *context, |
176 | const struct GNUNET_CHAT_Message *message); | 177 | const struct GNUNET_CHAT_Message *message); |
177 | 178 | ||
178 | /** | 179 | /** |
179 | * TODO | 180 | * Iterator over chat files in a specific chat context. |
180 | * | 181 | * |
181 | * @param cls | 182 | * @param[in/out] cls Closure from #GNUNET_CHAT_context_iterate_files |
182 | * @param context | 183 | * @param[in/out] context Chat context |
183 | * @param file | 184 | * @param[in/out] file Chat file |
184 | * @return | 185 | * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. |
185 | */ | 186 | */ |
186 | typedef int | 187 | typedef int |
187 | (*GNUNET_CHAT_ContextFileCallback) (void *cls, struct GNUNET_CHAT_Context *context, | 188 | (*GNUNET_CHAT_ContextFileCallback) (void *cls, struct GNUNET_CHAT_Context *context, |
188 | struct GNUNET_CHAT_File *file); | 189 | struct GNUNET_CHAT_File *file); |
189 | 190 | ||
190 | /** | 191 | /** |
191 | * TODO | 192 | * Iterator over chat contacts in a chat to check whether they received a |
193 | * specific message or not. | ||
192 | * | 194 | * |
193 | * @param cls | 195 | * @param[in/out] cls Closure from #GNUNET_CHAT_message_get_read_receipt |
194 | * @param message | 196 | * @param[in] message Chat message |
195 | * @param contact | 197 | * @param[in] contact Chat contact |
196 | * @param read_receipt | 198 | * @param[in] read_receipt #GNUNET_YES if the message was received by the contact, |
197 | * @return | 199 | * #GNUNET_NO otherwise |
200 | * @return #GNUNET_YES if we should continue to iterate, #GNUNET_NO otherwise. | ||
198 | */ | 201 | */ |
199 | typedef int | 202 | typedef int |
200 | (*GNUNET_CHAT_MessageReadReceiptCallback) (void *cls, const struct GNUNET_CHAT_Message *message, | 203 | (*GNUNET_CHAT_MessageReadReceiptCallback) (void *cls, const struct GNUNET_CHAT_Message *message, |
@@ -202,50 +205,57 @@ typedef int | |||
202 | int read_receipt); | 205 | int read_receipt); |
203 | 206 | ||
204 | /** | 207 | /** |
205 | * TODO | 208 | * Method called during an upload of a specific file in a chat to share it. |
206 | * | 209 | * |
207 | * @param cls | 210 | * @param[in/out] cls Closure from #GNUNET_CHAT_context_send_file |
208 | * @param file | 211 | * @param[in] file Chat file |
209 | * @param completed | 212 | * @param[in] completed Amount of the file being uploaded (in bytes) |
210 | * @param size | 213 | * @param[in] size Full size of the uploading file (in bytes) |
211 | */ | 214 | */ |
212 | typedef void | 215 | typedef void |
213 | (*GNUNET_CHAT_FileUploadCallback) (void *cls, const struct GNUNET_CHAT_File *file, | 216 | (*GNUNET_CHAT_FileUploadCallback) (void *cls, const struct GNUNET_CHAT_File *file, |
214 | uint64_t completed, uint64_t size); | 217 | uint64_t completed, uint64_t size); |
215 | 218 | ||
216 | /** | 219 | /** |
217 | * TODO | 220 | * Method called during a download of a specific file in a chat which was shared. |
218 | * | 221 | * |
219 | * @param cls | 222 | * @param[in/out] cls Closure from #GNUNET_CHAT_file_start_download |
220 | * @param file | 223 | * @param[in] file Chat file |
221 | * @param completed | 224 | * @param[in] completed Amount of the file being downloaded (in bytes) |
222 | * @param size | 225 | * @param[in] size Full size of the downloading file (in bytes) |
223 | */ | 226 | */ |
224 | typedef void | 227 | typedef void |
225 | (*GNUNET_CHAT_FileDownloadCallback) (void *cls, const struct GNUNET_CHAT_File *file, | 228 | (*GNUNET_CHAT_FileDownloadCallback) (void *cls, const struct GNUNET_CHAT_File *file, |
226 | uint64_t completed, uint64_t size); | 229 | uint64_t completed, uint64_t size); |
227 | 230 | ||
228 | /** | 231 | /** |
229 | * TODO | 232 | * Method called during an unindexing of a specific file in a chat which was |
233 | * uploaded before. | ||
230 | * | 234 | * |
231 | * @param cls | 235 | * @param[in/out] cls Closure from #GNUNET_CHAT_file_unindex |
232 | * @param file | 236 | * @param[in/out] file Chat file |
233 | * @param completed | 237 | * @param[in] completed Amount of the file being unindexed (in bytes) |
234 | * @param size | 238 | * @param[in] size Full size of the unindexing file (in bytes) |
235 | */ | 239 | */ |
236 | typedef void | 240 | typedef void |
237 | (*GNUNET_CHAT_FileUnindexCallback) (void *cls, struct GNUNET_CHAT_File *file, | 241 | (*GNUNET_CHAT_FileUnindexCallback) (void *cls, struct GNUNET_CHAT_File *file, |
238 | uint64_t completed, uint64_t size); | 242 | uint64_t completed, uint64_t size); |
239 | 243 | ||
240 | /** | 244 | /** |
241 | * TODO | 245 | * Start a chat handle with a certain configuration, an application <i>directory</i> |
246 | * and a selected user <i>name</i>. | ||
242 | * | 247 | * |
243 | * @param cfg | 248 | * A custom callback for warnings and message events can be provided optionally |
244 | * @param directory | 249 | * together with their respective closures. |
245 | * @param name | 250 | * |
246 | * @param warn_cb | 251 | * @param[in] cfg Configuration |
247 | * @param warn_cls | 252 | * @param[in] directory Application directory path (optional) |
248 | * @return | 253 | * @param[in] name User name (optional) |
254 | * @param[in] warn_cb Callback for warnings (optional) | ||
255 | * @param[in/out] warn_cls Closure for warnings (optional) | ||
256 | * @param[in] msg_cb Callback for message events (optional) | ||
257 | * @param[in/out] msg_cls Closure for message events (optional) | ||
258 | * @return Chat handle | ||
249 | */ | 259 | */ |
250 | struct GNUNET_CHAT_Handle* | 260 | struct GNUNET_CHAT_Handle* |
251 | GNUNET_CHAT_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | 261 | GNUNET_CHAT_start (const struct GNUNET_CONFIGURATION_Handle *cfg, |
@@ -255,58 +265,65 @@ GNUNET_CHAT_start (const struct GNUNET_CONFIGURATION_Handle *cfg, | |||
255 | GNUNET_CHAT_ContextMessageCallback msg_cb, void *msg_cls); | 265 | GNUNET_CHAT_ContextMessageCallback msg_cb, void *msg_cls); |
256 | 266 | ||
257 | /** | 267 | /** |
258 | * TODO | 268 | * Stops a chat handle closing all its remaining resources and frees the |
269 | * regarding memory. | ||
259 | * | 270 | * |
260 | * @param handle | 271 | * @param[in/out] handle Chat handle |
261 | */ | 272 | */ |
262 | void | 273 | void |
263 | GNUNET_CHAT_stop (struct GNUNET_CHAT_Handle *handle); | 274 | GNUNET_CHAT_stop (struct GNUNET_CHAT_Handle *handle); |
264 | 275 | ||
265 | /** | 276 | /** |
266 | * TODO | 277 | * Updates a chat handle to renew the used ego to sign sent messages in active |
278 | * chats. | ||
279 | * | ||
280 | * Updating the chat handle should only be used if necessary because the usage | ||
281 | * can require renewed exchanging of GNS entries. | ||
267 | * | 282 | * |
268 | * @param handle | 283 | * @param[in/out] handle Chat handle |
269 | * @return | 284 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
270 | */ | 285 | */ |
271 | int | 286 | int |
272 | GNUNET_CHAT_update (struct GNUNET_CHAT_Handle *handle); | 287 | GNUNET_CHAT_update (struct GNUNET_CHAT_Handle *handle); |
273 | 288 | ||
274 | /** | 289 | /** |
275 | * TODO | 290 | * Updates the name of a chat handle for related communication. |
276 | * | 291 | * |
277 | * @param handle | 292 | * @param[in/out] handle Chat handle |
278 | * @param name | 293 | * @param[in] name New name or NULL |
279 | * @return | 294 | * @return #GNUNET_YES on success, #GNUNET_NO on failure and #GNUNET_SYSERR if <i>handle</i> is NULL |
280 | */ | 295 | */ |
281 | int | 296 | int |
282 | GNUNET_CHAT_set_name (struct GNUNET_CHAT_Handle *handle, | 297 | GNUNET_CHAT_set_name (struct GNUNET_CHAT_Handle *handle, |
283 | const char *name); | 298 | const char *name); |
284 | 299 | ||
285 | /** | 300 | /** |
286 | * TODO | 301 | * Returns the name of a chat handle for related communication or NULL if no |
302 | * name is set. | ||
287 | * | 303 | * |
288 | * @param handle | 304 | * @param[in] handle Chat handle |
289 | * @return | 305 | * @return Name used by the handle or NULL |
290 | */ | 306 | */ |
291 | const char* | 307 | const char* |
292 | GNUNET_CHAT_get_name (const struct GNUNET_CHAT_Handle *handle); | 308 | GNUNET_CHAT_get_name (const struct GNUNET_CHAT_Handle *handle); |
293 | 309 | ||
294 | /** | 310 | /** |
295 | * TODO | 311 | * Returns the public key of the used ego to verify signatures of sent messages. |
296 | * | 312 | * |
297 | * @param handle | 313 | * @param[in] handle Chat handle |
298 | * @return | 314 | * @return Public key of the handles ego or NULL |
299 | */ | 315 | */ |
300 | const struct GNUNET_IDENTITY_PublicKey* | 316 | const struct GNUNET_IDENTITY_PublicKey* |
301 | GNUNET_CHAT_get_key (const struct GNUNET_CHAT_Handle *handle); | 317 | GNUNET_CHAT_get_key (const struct GNUNET_CHAT_Handle *handle); |
302 | 318 | ||
303 | /** | 319 | /** |
304 | * TODO | 320 | * Iterates through the contacts of a given chat <i>handle</i> with a selected |
321 | * callback and custom closure. | ||
305 | * | 322 | * |
306 | * @param handle | 323 | * @param[in/out] handle Chat handle |
307 | * @param callback | 324 | * @param[in] callback Callback for contact iteration (optional) |
308 | * @param cls | 325 | * @param[in/out] cls Closure for contact iteration (optional) |
309 | * @return | 326 | * @return Amount of contacts iterated or #GNUNET_SYSERR on failure |
310 | */ | 327 | */ |
311 | int | 328 | int |
312 | GNUNET_CHAT_iterate_contacts (struct GNUNET_CHAT_Handle *handle, | 329 | GNUNET_CHAT_iterate_contacts (struct GNUNET_CHAT_Handle *handle, |
@@ -314,22 +331,29 @@ GNUNET_CHAT_iterate_contacts (struct GNUNET_CHAT_Handle *handle, | |||
314 | void *cls); | 331 | void *cls); |
315 | 332 | ||
316 | /** | 333 | /** |
317 | * TODO | 334 | * Creates a new group chat to use with a given chat <i>handle</i> with an |
335 | * optional public <i>topic</i>. | ||
318 | * | 336 | * |
319 | * @param handle | 337 | * If a specific <i>topic</i> is used, the created group will be publically |
320 | * @return | 338 | * available to join for others searching for the used topic. Otherwise the |
339 | * group will be private using a randomly generated key and others can only | ||
340 | * join the chat via a private invitation. | ||
341 | * | ||
342 | * @param[in/out] handle Chat handle | ||
343 | * @return New group chat | ||
321 | */ | 344 | */ |
322 | struct GNUNET_CHAT_Group * | 345 | struct GNUNET_CHAT_Group * |
323 | GNUNET_CHAT_group_create (struct GNUNET_CHAT_Handle *handle, | 346 | GNUNET_CHAT_group_create (struct GNUNET_CHAT_Handle *handle, |
324 | const char* topic); | 347 | const char* topic); |
325 | 348 | ||
326 | /** | 349 | /** |
327 | * TODO | 350 | * Iterates through the groups of a given chat <i>handle</i> with a selected |
351 | * callback and custom closure. | ||
328 | * | 352 | * |
329 | * @param handle | 353 | * @param[in/out] handle Chat handle |
330 | * @param callback | 354 | * @param[in] callback Callback for group iteration (optional) |
331 | * @param cls | 355 | * @param[in/out] cls Closure for group iteration (optional) |
332 | * @return | 356 | * @return Amount of groups iterated or #GNUNET_SYSERR on failure |
333 | */ | 357 | */ |
334 | int | 358 | int |
335 | GNUNET_CHAT_iterate_groups (struct GNUNET_CHAT_Handle *handle, | 359 | GNUNET_CHAT_iterate_groups (struct GNUNET_CHAT_Handle *handle, |
@@ -337,134 +361,146 @@ GNUNET_CHAT_iterate_groups (struct GNUNET_CHAT_Handle *handle, | |||
337 | void *cls); | 361 | void *cls); |
338 | 362 | ||
339 | /** | 363 | /** |
340 | * TODO | 364 | * Leaves the private chat with a specific <i>contact</i> and frees the |
365 | * regarding memory of the contact if there remains no common chat with it. | ||
341 | * | 366 | * |
342 | * @param contact | 367 | * @param[in/out] contact Cntact |
343 | * @return | 368 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
344 | */ | 369 | */ |
345 | int | 370 | int |
346 | GNUNET_CHAT_contact_delete (struct GNUNET_CHAT_Contact *contact); | 371 | GNUNET_CHAT_contact_delete (struct GNUNET_CHAT_Contact *contact); |
347 | 372 | ||
348 | /** | 373 | /** |
349 | * TODO | 374 | * Overrides the name of a given <i>contact</i> with a custom nick <i>name</i> |
375 | * which will be only used locally. | ||
350 | * | 376 | * |
351 | * @param contact Contact | 377 | * @param[in/out] contact Contact |
352 | * @param name Custom nick name | 378 | * @param[in] name Custom nick name |
353 | */ | 379 | */ |
354 | void | 380 | void |
355 | GNUNET_CHAT_contact_set_name (struct GNUNET_CHAT_Contact *contact, | 381 | GNUNET_CHAT_contact_set_name (struct GNUNET_CHAT_Contact *contact, |
356 | const char *name); | 382 | const char *name); |
357 | 383 | ||
358 | /** | 384 | /** |
359 | * TODO | 385 | * Returns the provided name of a given <i>contact</i> or its custom nick name |
386 | * if it was overriden. | ||
360 | * | 387 | * |
361 | * @param contact Contact | 388 | * @param[in] contact Contact |
362 | * @return Name or custom nick name | 389 | * @return Name or custom nick name |
363 | */ | 390 | */ |
364 | const char* | 391 | const char* |
365 | GNUNET_CHAT_contact_get_name (const struct GNUNET_CHAT_Contact *contact); | 392 | GNUNET_CHAT_contact_get_name (const struct GNUNET_CHAT_Contact *contact); |
366 | 393 | ||
367 | /** | 394 | /** |
368 | * TODO | 395 | * Returns the public key of the used ego by a specific <i>contact</i> to |
396 | * verify signatures of sent messages. | ||
369 | * | 397 | * |
370 | * @param contact | 398 | * @param[in] contact Contact |
371 | * @return | 399 | * @return Public key of the contacts ego or NULL |
372 | */ | 400 | */ |
373 | const struct GNUNET_IDENTITY_PublicKey* | 401 | const struct GNUNET_IDENTITY_PublicKey* |
374 | GNUNET_CHAT_contact_get_key (const struct GNUNET_CHAT_Contact *contact); | 402 | GNUNET_CHAT_contact_get_key (const struct GNUNET_CHAT_Contact *contact); |
375 | 403 | ||
376 | /** | 404 | /** |
377 | * TODO | 405 | * Returns the chat context for a private chat with a given <i>contact</i>. |
378 | * | 406 | * |
379 | * @param contact Contact | 407 | * @param[in/out] contact Contact |
380 | * @return Chat context | 408 | * @return Chat context |
381 | */ | 409 | */ |
382 | struct GNUNET_CHAT_Context* | 410 | struct GNUNET_CHAT_Context* |
383 | GNUNET_CHAT_contact_get_context (struct GNUNET_CHAT_Contact *contact); | 411 | GNUNET_CHAT_contact_get_context (struct GNUNET_CHAT_Contact *contact); |
384 | 412 | ||
385 | /** | 413 | /** |
386 | * TODO | 414 | * Sets a custom <i>user pointer</i> to a given <i>contact</i> so it can be |
415 | * accessed in contact related callbacks. | ||
387 | * | 416 | * |
388 | * @param contact | 417 | * @param[in/out] contact Contact |
389 | * @param user_pointer | 418 | * @param[in] user_pointer Custom user pointer |
390 | * @return | ||
391 | */ | 419 | */ |
392 | void | 420 | void |
393 | GNUNET_CHAT_contact_set_user_pointer (struct GNUNET_CHAT_Contact *contact, | 421 | GNUNET_CHAT_contact_set_user_pointer (struct GNUNET_CHAT_Contact *contact, |
394 | void *user_pointer); | 422 | void *user_pointer); |
395 | 423 | ||
396 | /** | 424 | /** |
397 | * TODO | 425 | * Returns the custom user pointer of a given <i>contact</i> or NULL if it was |
426 | * not set any. | ||
398 | * | 427 | * |
399 | * @param contact | 428 | * @param[in] contact Contact |
400 | * @return | 429 | * @return Custom user pointer or NULL |
401 | */ | 430 | */ |
402 | void* | 431 | void* |
403 | GNUNET_CHAT_contact_get_user_pointer (const struct GNUNET_CHAT_Contact *contact); | 432 | GNUNET_CHAT_contact_get_user_pointer (const struct GNUNET_CHAT_Contact *contact); |
404 | 433 | ||
405 | /** | 434 | /** |
406 | * TODO | 435 | * Leaves a specific <i>group</i> chat and frees its memory if it is not shared |
436 | * with other groups or contacts. | ||
407 | * | 437 | * |
408 | * @param group | 438 | * @param[in/out] group Group |
409 | * @return | 439 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
410 | */ | 440 | */ |
411 | int | 441 | int |
412 | GNUNET_CHAT_group_leave (struct GNUNET_CHAT_Group *group); | 442 | GNUNET_CHAT_group_leave (struct GNUNET_CHAT_Group *group); |
413 | 443 | ||
414 | /** | 444 | /** |
415 | * TODO | 445 | * Sets the name of a given <i>group</i> to a custom nick <i>name</i> |
446 | * which will be only used locally. | ||
416 | * | 447 | * |
417 | * @param group | 448 | * @param[in/out] group Group |
418 | * @param name | 449 | * @param[in] name Custom nick name |
419 | */ | 450 | */ |
420 | void | 451 | void |
421 | GNUNET_CHAT_group_set_name (struct GNUNET_CHAT_Group *group, | 452 | GNUNET_CHAT_group_set_name (struct GNUNET_CHAT_Group *group, |
422 | const char *name); | 453 | const char *name); |
423 | 454 | ||
424 | /** | 455 | /** |
425 | * TODO | 456 | * Returns the custom nick name of a given <i>group</i> if it was overriden. |
426 | * | 457 | * |
427 | * @param group | 458 | * @param[in] group Group |
428 | * @return | 459 | * @return Custom nick name or NULL |
429 | */ | 460 | */ |
430 | const char* | 461 | const char* |
431 | GNUNET_CHAT_group_get_name (const struct GNUNET_CHAT_Group *group); | 462 | GNUNET_CHAT_group_get_name (const struct GNUNET_CHAT_Group *group); |
432 | 463 | ||
433 | /** | 464 | /** |
434 | * TODO | 465 | * Sets a custom <i>user pointer</i> to a given <i>group</i> so it can be |
466 | * accessed in group related callbacks. | ||
435 | * | 467 | * |
436 | * @param group | 468 | * @param[in/out] group Group |
437 | * @param user_pointer | 469 | * @param[in] user_pointer Custom user pointer |
438 | */ | 470 | */ |
439 | void | 471 | void |
440 | GNUNET_CHAT_group_set_user_pointer (struct GNUNET_CHAT_Group *group, | 472 | GNUNET_CHAT_group_set_user_pointer (struct GNUNET_CHAT_Group *group, |
441 | void *user_pointer); | 473 | void *user_pointer); |
442 | 474 | ||
443 | /** | 475 | /** |
444 | * TODO | 476 | * Returns the custom user pointer of a given <i>group</i> or NULL if it was |
477 | * not set any. | ||
445 | * | 478 | * |
446 | * @param group | 479 | * @param[in] group Group |
480 | * @return Custom user pointer or NULL | ||
447 | */ | 481 | */ |
448 | void* | 482 | void* |
449 | GNUNET_CHAT_group_get_user_pointer (const struct GNUNET_CHAT_Group *group); | 483 | GNUNET_CHAT_group_get_user_pointer (const struct GNUNET_CHAT_Group *group); |
450 | 484 | ||
451 | /** | 485 | /** |
452 | * TODO | 486 | * Invites a specific <i>contact</i> to a given <i>group</i> via a privately |
487 | * sent invitation. | ||
453 | * | 488 | * |
454 | * @param group | 489 | * @param[in/out] group Group |
455 | * @param contact | 490 | * @param[in/out] contact Contact |
456 | */ | 491 | */ |
457 | void | 492 | void |
458 | GNUNET_CHAT_group_invite_contact (struct GNUNET_CHAT_Group *group, | 493 | GNUNET_CHAT_group_invite_contact (struct GNUNET_CHAT_Group *group, |
459 | struct GNUNET_CHAT_Contact *contact); | 494 | struct GNUNET_CHAT_Contact *contact); |
460 | 495 | ||
461 | /** | 496 | /** |
462 | * TODO | 497 | * Iterates through the contacts of a given <i>group</i> with a selected |
498 | * callback and custom closure. | ||
463 | * | 499 | * |
464 | * @param group | 500 | * @param[in/out] group Group |
465 | * @param callback | 501 | * @param[in] callback Callback for contact iteration (optional) |
466 | * @param cls | 502 | * @param[in/out] cls Closure for contact iteration (optional) |
467 | * @return | 503 | * @return Amount of contacts iterated or #GNUNET_SYSERR on failure |
468 | */ | 504 | */ |
469 | int | 505 | int |
470 | GNUNET_CHAT_group_iterate_contacts (struct GNUNET_CHAT_Group *group, | 506 | GNUNET_CHAT_group_iterate_contacts (struct GNUNET_CHAT_Group *group, |
@@ -472,49 +508,56 @@ GNUNET_CHAT_group_iterate_contacts (struct GNUNET_CHAT_Group *group, | |||
472 | void *cls); | 508 | void *cls); |
473 | 509 | ||
474 | /** | 510 | /** |
475 | * TODO | 511 | * Returns the chat context for a chat with a given <i>group</i>. |
476 | * | 512 | * |
477 | * @param group | 513 | * @param[in/out] group Group |
478 | * @return | 514 | * @return Chat context |
479 | */ | 515 | */ |
480 | struct GNUNET_CHAT_Context* | 516 | struct GNUNET_CHAT_Context* |
481 | GNUNET_CHAT_group_get_context (struct GNUNET_CHAT_Group *group); | 517 | GNUNET_CHAT_group_get_context (struct GNUNET_CHAT_Group *group); |
482 | 518 | ||
483 | /** | 519 | /** |
484 | * TODO | 520 | * Sets a custom <i>user pointer</i> to a given chat <i>context</i> so it can |
521 | * be accessed in chat context related callbacks. | ||
485 | * | 522 | * |
486 | * @param context | 523 | * @param[in/out] context Chat context |
487 | * @param user_pointer | 524 | * @param[in] user_pointer Custom user pointer |
488 | */ | 525 | */ |
489 | void | 526 | void |
490 | GNUNET_CHAT_context_set_user_pointer (struct GNUNET_CHAT_Context *context, | 527 | GNUNET_CHAT_context_set_user_pointer (struct GNUNET_CHAT_Context *context, |
491 | void *user_pointer); | 528 | void *user_pointer); |
492 | 529 | ||
493 | /** | 530 | /** |
494 | * TODO | 531 | * Returns the custom user pointer of a given chat <i>context</i> or NULL if it |
532 | * was not set any. | ||
495 | * | 533 | * |
496 | * @param context | 534 | * @param[in] context Chat context |
535 | * @return Custom user pointer or NULL | ||
497 | */ | 536 | */ |
498 | void* | 537 | void* |
499 | GNUNET_CHAT_context_get_user_pointer (const struct GNUNET_CHAT_Context *context); | 538 | GNUNET_CHAT_context_get_user_pointer (const struct GNUNET_CHAT_Context *context); |
500 | 539 | ||
501 | /** | 540 | /** |
502 | * TODO | 541 | * Sends a selected <i>text</i> into a given chat <i>context</i>. |
503 | * | 542 | * |
504 | * @param context | 543 | * @param[in/out] context Chat context |
505 | * @param text | 544 | * @param[in] text Text |
506 | * @return | 545 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
507 | */ | 546 | */ |
508 | int | 547 | int |
509 | GNUNET_CHAT_context_send_text (struct GNUNET_CHAT_Context *context, | 548 | GNUNET_CHAT_context_send_text (struct GNUNET_CHAT_Context *context, |
510 | const char *text); | 549 | const char *text); |
511 | 550 | ||
512 | /** | 551 | /** |
513 | * TODO | 552 | * Uploads a local file specified via its <i>path</i> using symmetric encryption |
553 | * and shares the regarding information to download and decrypt it in a given | ||
554 | * chat <i>context</i>. | ||
514 | * | 555 | * |
515 | * @param context | 556 | * @param[in/out] context Chat context |
516 | * @param path | 557 | * @param[in] path Local file path |
517 | * @return | 558 | * @param[in] callback Callback for file uploading (optional) |
559 | * @param[in/out] cls Closure for file uploading (optional) | ||
560 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | ||
518 | */ | 561 | */ |
519 | int | 562 | int |
520 | GNUNET_CHAT_context_send_file (struct GNUNET_CHAT_Context *context, | 563 | GNUNET_CHAT_context_send_file (struct GNUNET_CHAT_Context *context, |
@@ -523,23 +566,25 @@ GNUNET_CHAT_context_send_file (struct GNUNET_CHAT_Context *context, | |||
523 | void *cls); | 566 | void *cls); |
524 | 567 | ||
525 | /** | 568 | /** |
526 | * TODO | 569 | * Shares the information to download and decrypt a specific <i>file</i> from |
570 | * another chat in a given chat <i>context</i>. | ||
527 | * | 571 | * |
528 | * @param context | 572 | * @param[in/out] context Chat context |
529 | * @param file | 573 | * @param[in] file File handle |
530 | * @return | 574 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
531 | */ | 575 | */ |
532 | int | 576 | int |
533 | GNUNET_CHAT_context_share_file (struct GNUNET_CHAT_Context *context, | 577 | GNUNET_CHAT_context_share_file (struct GNUNET_CHAT_Context *context, |
534 | const struct GNUNET_CHAT_File *file); | 578 | const struct GNUNET_CHAT_File *file); |
535 | 579 | ||
536 | /** | 580 | /** |
537 | * TODO | 581 | * Iterates through the contacts of a given chat <i>context</i> with a selected |
582 | * callback and custom closure. | ||
538 | * | 583 | * |
539 | * @param context | 584 | * @param[in/out] context Chat context |
540 | * @param callback | 585 | * @param[in] callback Callback for contact iteration (optional) |
541 | * @param cls | 586 | * @param[in/out] cls Closure for contact iteration (optional) |
542 | * @return | 587 | * @return Amount of contacts iterated or #GNUNET_SYSERR on failure |
543 | */ | 588 | */ |
544 | int | 589 | int |
545 | GNUNET_CHAT_context_iterate_messages (struct GNUNET_CHAT_Context *context, | 590 | GNUNET_CHAT_context_iterate_messages (struct GNUNET_CHAT_Context *context, |
@@ -547,12 +592,13 @@ GNUNET_CHAT_context_iterate_messages (struct GNUNET_CHAT_Context *context, | |||
547 | void *cls); | 592 | void *cls); |
548 | 593 | ||
549 | /** | 594 | /** |
550 | * TODO | 595 | * Iterates through the files of a given chat <i>context</i> with a selected |
596 | * callback and custom closure. | ||
551 | * | 597 | * |
552 | * @param context | 598 | * @param[in/out] context Chat context |
553 | * @param callback | 599 | * @param[in] callback Callback for file iteration (optional) |
554 | * @param cls | 600 | * @param[in/out] cls Closure for file iteration (optional) |
555 | * @return | 601 | * @return Amount of files iterated or #GNUNET_SYSERR on failure |
556 | */ | 602 | */ |
557 | int | 603 | int |
558 | GNUNET_CHAT_context_iterate_files (struct GNUNET_CHAT_Context *context, | 604 | GNUNET_CHAT_context_iterate_files (struct GNUNET_CHAT_Context *context, |
@@ -560,57 +606,62 @@ GNUNET_CHAT_context_iterate_files (struct GNUNET_CHAT_Context *context, | |||
560 | void *cls); | 606 | void *cls); |
561 | 607 | ||
562 | /** | 608 | /** |
563 | * TODO | 609 | * Returns the kind of a given <i>message</i> to determine its content and |
610 | * related usage. | ||
564 | * | 611 | * |
565 | * @param message | 612 | * @param[in] message Message |
566 | * @return | 613 | * @return The kind of message |
567 | */ | 614 | */ |
568 | enum GNUNET_CHAT_MessageKind | 615 | enum GNUNET_CHAT_MessageKind |
569 | GNUNET_CHAT_message_get_kind (const struct GNUNET_CHAT_Message *message); | 616 | GNUNET_CHAT_message_get_kind (const struct GNUNET_CHAT_Message *message); |
570 | 617 | ||
571 | /** | 618 | /** |
572 | * TODO | 619 | * Returns the timestamp of a given <i>message</i> in absolute measure. |
573 | * | 620 | * |
574 | * @param message | 621 | * @param[in] message Message |
575 | * @return | 622 | * @return The timestamp of message |
576 | */ | 623 | */ |
577 | struct GNUNET_TIME_Absolute | 624 | struct GNUNET_TIME_Absolute |
578 | GNUNET_CHAT_message_get_timestamp (const struct GNUNET_CHAT_Message *message); | 625 | GNUNET_CHAT_message_get_timestamp (const struct GNUNET_CHAT_Message *message); |
579 | 626 | ||
580 | /** | 627 | /** |
581 | * TODO | 628 | * Returns the contact of the sender from a given <i>message</i>. |
582 | * | 629 | * |
583 | * @param message | 630 | * @param[in] message Message |
584 | * @return | 631 | * @return Contact of the messages sender |
585 | */ | 632 | */ |
586 | const struct GNUNET_CHAT_Contact* | 633 | const struct GNUNET_CHAT_Contact* |
587 | GNUNET_CHAT_message_get_sender (const struct GNUNET_CHAT_Message *message); | 634 | GNUNET_CHAT_message_get_sender (const struct GNUNET_CHAT_Message *message); |
588 | 635 | ||
589 | /** | 636 | /** |
590 | * TODO | 637 | * Returns #GNUNET_YES if the message was sent by the related chat handle, |
638 | * otherwise it returns #GNUNET_NO. | ||
591 | * | 639 | * |
592 | * @param message | 640 | * @param[in] message Message |
593 | * @return | 641 | * @return #GNUNET_YES if the message was sent, otherwise #GNUNET_NO |
594 | */ | 642 | */ |
595 | int | 643 | int |
596 | GNUNET_CHAT_message_is_sent (const struct GNUNET_CHAT_Message *message); | 644 | GNUNET_CHAT_message_is_sent (const struct GNUNET_CHAT_Message *message); |
597 | 645 | ||
598 | /** | 646 | /** |
599 | * TODO | 647 | * Returns #GNUNET_YES if the message was received privately encrypted by the |
648 | * related chat handle, otherwise it returns #GNUNET_NO. | ||
600 | * | 649 | * |
601 | * @param message | 650 | * @param[in] message Message |
602 | * @return | 651 | * @return #GNUNET_YES if the message was privately received, |
652 | * otherwise #GNUNET_NO | ||
603 | */ | 653 | */ |
604 | int | 654 | int |
605 | GNUNET_CHAT_message_is_private (const struct GNUNET_CHAT_Message *message); | 655 | GNUNET_CHAT_message_is_private (const struct GNUNET_CHAT_Message *message); |
606 | 656 | ||
607 | /** | 657 | /** |
608 | * TODO | 658 | * Iterates through the contacts of the context related to a given chat |
659 | * <i>message</i> to check whether it was received by each of the contacts. | ||
609 | * | 660 | * |
610 | * @param message | 661 | * @param[in] message Message |
611 | * @param callback | 662 | * @param[in] callback Callback for contact iteration (optional) |
612 | * @param cls | 663 | * @param[in/out] cls Closure for contact iteration (optional) |
613 | * @return | 664 | * @return Amount of contacts iterated or #GNUNET_SYSERR on failure |
614 | */ | 665 | */ |
615 | int | 666 | int |
616 | GNUNET_CHAT_message_get_read_receipt (const struct GNUNET_CHAT_Message *message, | 667 | GNUNET_CHAT_message_get_read_receipt (const struct GNUNET_CHAT_Message *message, |
@@ -618,95 +669,104 @@ GNUNET_CHAT_message_get_read_receipt (const struct GNUNET_CHAT_Message *message, | |||
618 | void *cls); | 669 | void *cls); |
619 | 670 | ||
620 | /** | 671 | /** |
621 | * TODO | 672 | * Returns the text of a given <i>message</i> if its kind is |
673 | * #GNUNET_CHAT_KIND_TEXT, otherwise it returns NULL. | ||
622 | * | 674 | * |
623 | * @param message | 675 | * @param[in] message Message |
624 | * @return | 676 | * @return The text of message or NULL |
625 | */ | 677 | */ |
626 | const char* | 678 | const char* |
627 | GNUNET_CHAT_message_get_text (const struct GNUNET_CHAT_Message *message); | 679 | GNUNET_CHAT_message_get_text (const struct GNUNET_CHAT_Message *message); |
628 | 680 | ||
629 | 681 | ||
630 | /** | 682 | /** |
631 | * TODO | 683 | * Returns the file handle of a given <i>message</i> if its kind is |
684 | * #GNUNET_CHAT_KIND_FILE, otherwise it returns NULL. | ||
632 | * | 685 | * |
633 | * @param message | 686 | * @param[in] message Message |
634 | * @return | 687 | * @return The file handle of message or NULL |
635 | */ | 688 | */ |
636 | struct GNUNET_CHAT_File* | 689 | struct GNUNET_CHAT_File* |
637 | GNUNET_CHAT_message_get_file (const struct GNUNET_CHAT_Message *message); | 690 | GNUNET_CHAT_message_get_file (const struct GNUNET_CHAT_Message *message); |
638 | 691 | ||
639 | /** | 692 | /** |
640 | * TODO | 693 | * Returns the invitation of a given <i>message</i> if its kind is |
694 | * #GNUNET_CHAT_KIND_INVITATION, otherwise it returns NULL. | ||
641 | * | 695 | * |
642 | * @param message | 696 | * @param[in] message Message |
643 | * @return | 697 | * @return The invitation of message or NULL |
644 | */ | 698 | */ |
645 | struct GNUNET_CHAT_Invitation* | 699 | struct GNUNET_CHAT_Invitation* |
646 | GNUNET_CHAT_message_get_invitation (const struct GNUNET_CHAT_Message *message); | 700 | GNUNET_CHAT_message_get_invitation (const struct GNUNET_CHAT_Message *message); |
647 | 701 | ||
648 | /** | 702 | /** |
649 | * TODO | 703 | * Deletes a given <i>message</i> with a specific relative <i>delay</i>. |
650 | * | 704 | * |
651 | * @param message | 705 | * @param[in] message Message |
652 | * @param delay | 706 | * @param[in] delay Relative delay |
653 | * @return | 707 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
654 | */ | 708 | */ |
655 | int | 709 | int |
656 | GNUNET_CHAT_message_delete (const struct GNUNET_CHAT_Message *message, | 710 | GNUNET_CHAT_message_delete (const struct GNUNET_CHAT_Message *message, |
657 | struct GNUNET_TIME_Relative delay); | 711 | struct GNUNET_TIME_Relative delay); |
658 | 712 | ||
659 | /** | 713 | /** |
660 | * TODO | 714 | * Returns the hash of a given <i>file</i> handle. |
661 | * | 715 | * |
662 | * @param file | 716 | * @param[in] file File handle |
663 | * @return | 717 | * @return The hash of file |
664 | */ | 718 | */ |
665 | const struct GNUNET_HashCode* | 719 | const struct GNUNET_HashCode* |
666 | GNUNET_CHAT_file_get_hash (const struct GNUNET_CHAT_File *file); | 720 | GNUNET_CHAT_file_get_hash (const struct GNUNET_CHAT_File *file); |
667 | 721 | ||
668 | /** | 722 | /** |
669 | * TODO | 723 | * Returns the file size of a given <i>file</i> handle. |
670 | * | 724 | * |
671 | * @param file | 725 | * @param[in] file File handle |
672 | * @return | 726 | * @return The file size of file |
673 | */ | 727 | */ |
674 | uint64_t | 728 | uint64_t |
675 | GNUNET_CHAT_file_get_size (const struct GNUNET_CHAT_File *file); | 729 | GNUNET_CHAT_file_get_size (const struct GNUNET_CHAT_File *file); |
676 | 730 | ||
677 | /** | 731 | /** |
678 | * TODO | 732 | * Checks whether a file locally exists of a given <i>file</i> handle and |
733 | * returns #GNUNET_YES in that case, otherwise #GNUNET_NO. | ||
679 | * | 734 | * |
680 | * @param file | 735 | * @param[in] file File handle |
681 | * @return | 736 | * @return #GNUNET_YES if the file exists locally, otherwise #GNUNET_NO |
682 | */ | 737 | */ |
683 | int | 738 | int |
684 | GNUNET_CHAT_file_is_local (const struct GNUNET_CHAT_File *file); | 739 | GNUNET_CHAT_file_is_local (const struct GNUNET_CHAT_File *file); |
685 | 740 | ||
686 | /** | 741 | /** |
687 | * TODO | 742 | * Sets a custom <i>user pointer</i> to a given <i>file</i> handle so it can |
743 | * be accessed in file related callbacks. | ||
688 | * | 744 | * |
689 | * @param file | 745 | * @param[in/out] file File handle |
690 | * @param user_pointer | 746 | * @param[in] user_pointer Custom user pointer |
691 | */ | 747 | */ |
692 | void | 748 | void |
693 | GNUNET_CHAT_file_set_user_pointer (struct GNUNET_CHAT_File *file, | 749 | GNUNET_CHAT_file_set_user_pointer (struct GNUNET_CHAT_File *file, |
694 | void *user_pointer); | 750 | void *user_pointer); |
695 | 751 | ||
696 | /** | 752 | /** |
697 | * TODO | 753 | * Returns the custom user pointer of a given <i>file</i> handle or NULL if it |
754 | * was not set any. | ||
698 | * | 755 | * |
699 | * @param file | 756 | * @param[in] file File handle |
700 | * @return | 757 | * @return Custom user pointer |
701 | */ | 758 | */ |
702 | void* | 759 | void* |
703 | GNUNET_CHAT_file_get_user_pointer (const struct GNUNET_CHAT_File *file); | 760 | GNUNET_CHAT_file_get_user_pointer (const struct GNUNET_CHAT_File *file); |
704 | 761 | ||
705 | /** | 762 | /** |
706 | * TODO | 763 | * Starts downloading a file from a given <i>file</i> handle and sets up a |
764 | * selected callback and custom closure for its progress. | ||
707 | * | 765 | * |
708 | * @param file | 766 | * @param[in/out] file File handle |
709 | * @return | 767 | * @param[in] callback Callback for file downloading (optional) |
768 | * @param[in/out] cls Closure for file downloading (optional) | ||
769 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | ||
710 | */ | 770 | */ |
711 | int | 771 | int |
712 | GNUNET_CHAT_file_start_download (struct GNUNET_CHAT_File *file, | 772 | GNUNET_CHAT_file_start_download (struct GNUNET_CHAT_File *file, |
@@ -714,39 +774,40 @@ GNUNET_CHAT_file_start_download (struct GNUNET_CHAT_File *file, | |||
714 | void *cls); | 774 | void *cls); |
715 | 775 | ||
716 | /** | 776 | /** |
717 | * TODO | 777 | * Pause downloading a file from a given <i>file</i> handle. |
718 | * | 778 | * |
719 | * @param file | 779 | * @param[in/out] file File handle |
720 | * @return | 780 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
721 | */ | 781 | */ |
722 | int | 782 | int |
723 | GNUNET_CHAT_file_pause_download (struct GNUNET_CHAT_File *file); | 783 | GNUNET_CHAT_file_pause_download (struct GNUNET_CHAT_File *file); |
724 | 784 | ||
725 | /** | 785 | /** |
726 | * TODO | 786 | * Resume downloading a file from a given <i>file</i> handle. |
727 | * | 787 | * |
728 | * @param file | 788 | * @param[in/out] file File handle |
729 | * @return | 789 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
730 | */ | 790 | */ |
731 | int | 791 | int |
732 | GNUNET_CHAT_file_resume_download (struct GNUNET_CHAT_File *file); | 792 | GNUNET_CHAT_file_resume_download (struct GNUNET_CHAT_File *file); |
733 | 793 | ||
734 | /** | 794 | /** |
735 | * TODO | 795 | * Stops downloading a file from a given <i>file</i> handle. |
736 | * | 796 | * |
737 | * @param file | 797 | * @param[in/out] file File handle |
738 | * @return | 798 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
739 | */ | 799 | */ |
740 | int | 800 | int |
741 | GNUNET_CHAT_file_stop_download (struct GNUNET_CHAT_File *file); | 801 | GNUNET_CHAT_file_stop_download (struct GNUNET_CHAT_File *file); |
742 | 802 | ||
743 | /** | 803 | /** |
744 | * TODO | 804 | * Unindexes an uploaded file from a given <i>file</i> handle with a selected |
805 | * callback and a custom closure. | ||
745 | * | 806 | * |
746 | * @param file | 807 | * @param[in/out] file File handle |
747 | * @param callback | 808 | * @param[in] callback Callback for file unindexing (optional) |
748 | * @param cls | 809 | * @param[in/out] cls Closure for file unindexing (optional) |
749 | * @return | 810 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure |
750 | */ | 811 | */ |
751 | int | 812 | int |
752 | GNUNET_CHAT_file_unindex (struct GNUNET_CHAT_File *file, | 813 | GNUNET_CHAT_file_unindex (struct GNUNET_CHAT_File *file, |
@@ -754,9 +815,9 @@ GNUNET_CHAT_file_unindex (struct GNUNET_CHAT_File *file, | |||
754 | void *cls); | 815 | void *cls); |
755 | 816 | ||
756 | /** | 817 | /** |
757 | * TODO | 818 | * Accepts a given chat <i>invitation</i> to enter another chat. |
758 | * | 819 | * |
759 | * @param invitation | 820 | * @param[in/out] invitation Chat invitation |
760 | */ | 821 | */ |
761 | void | 822 | void |
762 | GNUNET_CHAT_invitation_accept (struct GNUNET_CHAT_Invitation *invitation); | 823 | GNUNET_CHAT_invitation_accept (struct GNUNET_CHAT_Invitation *invitation); |
diff --git a/src/gnunet_chat_lib.c b/src/gnunet_chat_lib.c index 32e7082..ab5da74 100644 --- a/src/gnunet_chat_lib.c +++ b/src/gnunet_chat_lib.c | |||
@@ -923,7 +923,7 @@ GNUNET_CHAT_file_start_download (struct GNUNET_CHAT_File *file, | |||
923 | file_bind_downlaod(file, callback, cls); | 923 | file_bind_downlaod(file, callback, cls); |
924 | 924 | ||
925 | GNUNET_FS_download_resume(file->download); | 925 | GNUNET_FS_download_resume(file->download); |
926 | return GNUNET_NO; | 926 | return GNUNET_OK; |
927 | } | 927 | } |
928 | 928 | ||
929 | const uint64_t size = GNUNET_FS_uri_chk_get_file_size(file->uri); | 929 | const uint64_t size = GNUNET_FS_uri_chk_get_file_size(file->uri); |
@@ -942,7 +942,7 @@ GNUNET_CHAT_file_start_download (struct GNUNET_CHAT_File *file, | |||
942 | if (callback) | 942 | if (callback) |
943 | callback(cls, file, size, size); | 943 | callback(cls, file, size, size); |
944 | 944 | ||
945 | return GNUNET_YES; | 945 | return GNUNET_OK; |
946 | } | 946 | } |
947 | 947 | ||
948 | file_bind_downlaod(file, callback, cls); | 948 | file_bind_downlaod(file, callback, cls); |
@@ -964,7 +964,7 @@ GNUNET_CHAT_file_start_download (struct GNUNET_CHAT_File *file, | |||
964 | ); | 964 | ); |
965 | 965 | ||
966 | GNUNET_free(filename); | 966 | GNUNET_free(filename); |
967 | return GNUNET_YES; | 967 | return GNUNET_OK; |
968 | } | 968 | } |
969 | 969 | ||
970 | 970 | ||