summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCedric BAIL <cedric@osg.samsung.com>2015-10-01 14:12:50 -0700
committerCedric BAIL <cedric@osg.samsung.com>2015-10-01 14:24:46 -0700
commit66d38965fdf99f244b526040e7e1289ac42a2d14 (patch)
tree68a91d5a10f46106244bbe296db677e275d5d054
parentffee0948c691d1630036a5be7ec4da89d50c4851 (diff)
eio: improve documentation.
This set of documentation update basically make it clearer that Eio use Eina and do cross linking of function used by Eio to Eina. It also copy some of the warning coming from Eina documentation into Eio.
-rw-r--r--src/lib/eio/Eio.h179
1 files changed, 122 insertions, 57 deletions
diff --git a/src/lib/eio/Eio.h b/src/lib/eio/Eio.h
index 3a9a2814d8..9f139df4c9 100644
--- a/src/lib/eio/Eio.h
+++ b/src/lib/eio/Eio.h
@@ -142,6 +142,8 @@ extern "C" {
142 * Recommended reading: 142 * Recommended reading:
143 * 143 *
144 * @li @ref Eio_Helper for common functions and library initialization. 144 * @li @ref Eio_Helper for common functions and library initialization.
145 * @li @ref Eio_List for listing files asynchronous.
146 * @li @ref Eio_Management for anyone who want to do a file manager (copy, rm, ...).
145 * @li @ref Eio_Map to manipulate files asynchronously (mmap). 147 * @li @ref Eio_Map to manipulate files asynchronously (mmap).
146 * @li @ref Eio_Xattr to access file extended attributes (xattr). 148 * @li @ref Eio_Xattr to access file extended attributes (xattr).
147 * @li @ref Eio_Monitor to monitor for file changes (inotify). 149 * @li @ref Eio_Monitor to monitor for file changes (inotify).
@@ -153,7 +155,6 @@ extern "C" {
153 * 155 *
154 * More examples can be found at @ref eio_examples. 156 * More examples can be found at @ref eio_examples.
155 * 157 *
156 * @{
157 */ 158 */
158 159
159/** 160/**
@@ -185,6 +186,18 @@ enum _Eio_File_Op
185typedef enum _Eio_File_Op Eio_File_Op; 186typedef enum _Eio_File_Op Eio_File_Op;
186 187
187/** 188/**
189 * @defgroup Eio_List Eio file listing API
190 * @ingroup Eio
191 *
192 * @brief This functions helps list files asynchronously.
193 *
194 * This set of functions work on top of Eina_File and Ecore_Thread
195 * to list files under various condition.
196 *
197 * @{
198 */
199
200/**
188 * @typedef Eio_File 201 * @typedef Eio_File
189 * Generic asynchronous I/O reference. 202 * Generic asynchronous I/O reference.
190 */ 203 */
@@ -252,14 +265,20 @@ struct _Eio_Progress
252 * It's equivalent to the "ls" shell command. Every file will be passed to the 265 * It's equivalent to the "ls" shell command. Every file will be passed to the
253 * filter_cb, so it's your job to decide if you want to pass the file to the 266 * filter_cb, so it's your job to decide if you want to pass the file to the
254 * main_cb or not. Return EINA_TRUE to pass it to the main_cb or EINA_FALSE to 267 * main_cb or not. Return EINA_TRUE to pass it to the main_cb or EINA_FALSE to
255 * ignore it. 268 * ignore it. It runs eina_file_ls() in a separate thread using
269 * ecore_thread_feedback_run().
270 *
271 * @see eina_file_ls()
272 * @see ecore_thread_feedback_run()
273 * @see eio_file_direct_ls()
274 * @see eio_file_stat_ls()
256 */ 275 */
257EAPI Eio_File *eio_file_ls(const char *dir, 276EAPI Eio_File *eio_file_ls(const char *dir,
258 Eio_Filter_Cb filter_cb, 277 Eio_Filter_Cb filter_cb,
259 Eio_Main_Cb main_cb, 278 Eio_Main_Cb main_cb,
260 Eio_Done_Cb done_cb, 279 Eio_Done_Cb done_cb,
261 Eio_Error_Cb error_cb, 280 Eio_Error_Cb error_cb,
262 const void *data); 281 const void *data);
263 282
264/** 283/**
265 * @brief List contents of a directory without locking your app. 284 * @brief List contents of a directory without locking your app.
@@ -271,18 +290,30 @@ EAPI Eio_File *eio_file_ls(const char *dir,
271 * @param data Unmodified user data passed to callbacks 290 * @param data Unmodified user data passed to callbacks
272 * @return A reference to the I/O operation. 291 * @return A reference to the I/O operation.
273 * 292 *
274 * eio_file_direct_ls runs eina_file_direct_ls in a separate thread using 293 * eio_file_direct_ls() runs eina_file_direct_ls() in a separate thread using
275 * ecore_thread_feedback_run. This prevents any blocking in your apps. 294 * ecore_thread_feedback_run(). This prevents any blocking in your apps.
276 * Every file will be passed to the filter_cb, so it's your job to decide if you 295 * Every file will be passed to the filter_cb, so it's your job to decide if you
277 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to 296 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to
278 * the main_cb or EINA_FALSE to ignore it. 297 * the main_cb or EINA_FALSE to ignore it.
298 *
299 * @warning If readdir_r doesn't contain file type information, file type is
300 * EINA_FILE_UNKNOWN.
301 *
302 * @note The iterator walks over '.' and '..' without returning them.
303 * @note The difference between this function and eina_file_stat_ls() is that
304 * it may not get the file type information however it is likely to be
305 * faster.
306 *
307 * @see eio_file_stat_ls()
308 * @see eina_file_direct_ls()
309 * @see ecore_thread_feedback_run()
279 */ 310 */
280EAPI Eio_File *eio_file_direct_ls(const char *dir, 311EAPI Eio_File *eio_file_direct_ls(const char *dir,
281 Eio_Filter_Direct_Cb filter_cb, 312 Eio_Filter_Direct_Cb filter_cb,
282 Eio_Main_Direct_Cb main_cb, 313 Eio_Main_Direct_Cb main_cb,
283 Eio_Done_Cb done_cb, 314 Eio_Done_Cb done_cb,
284 Eio_Error_Cb error_cb, 315 Eio_Error_Cb error_cb,
285 const void *data); 316 const void *data);
286 317
287/** 318/**
288 * @brief List content of a directory without locking your app. 319 * @brief List content of a directory without locking your app.
@@ -296,8 +327,17 @@ EAPI Eio_File *eio_file_direct_ls(const char *dir,
296 * 327 *
297 * Every file will be passed to the filter_cb, so it's your job to decide if you 328 * Every file will be passed to the filter_cb, so it's your job to decide if you
298 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to 329 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to
299 * the main_cb or EINA_FALSE to ignore it. 330 * the main_cb or EINA_FALSE to ignore it. eio_file_stat_ls() run eina_file_stat_ls()
331 * in a separate thread using ecore_thread_feedback_run().
332 *
333 * @note The iterator walks over '.' and '..' without returning them.
334 * @note The difference between this function and eio_file_direct_ls() is that
335 * it guarantees the file type information to be correct by incurring a
336 * possible performance penalty.
300 * 337 *
338 * @see eio_file_stat_ls()
339 * @see eina_file_stat_ls()
340 * @see ecore_thread_feedback_run()
301 */ 341 */
302EAPI Eio_File *eio_file_stat_ls(const char *dir, 342EAPI Eio_File *eio_file_stat_ls(const char *dir,
303 Eio_Filter_Direct_Cb filter_cb, 343 Eio_Filter_Direct_Cb filter_cb,
@@ -317,11 +357,16 @@ EAPI Eio_File *eio_file_stat_ls(const char *dir,
317 * @return A reference to the I/O operation. 357 * @return A reference to the I/O operation.
318 * 358 *
319 * eio_dir_stat_ls() runs eina_file_stat_ls() recursively in a separate thread using 359 * eio_dir_stat_ls() runs eina_file_stat_ls() recursively in a separate thread using
320 * ecore_thread_feedback_run. This prevents any blocking in your apps. 360 * ecore_thread_feedback_run(). This prevents any blocking in your apps.
321 * Every file will be passed to the 361 * Every file will be passed to the
322 * filter_cb, so it's your job to decide if you want to pass the file to the 362 * filter_cb, so it's your job to decide if you want to pass the file to the
323 * main_cb or not. Return EINA_TRUE to pass it to the main_cb or EINA_FALSE to 363 * main_cb or not. Return EINA_TRUE to pass it to the main_cb or EINA_FALSE to
324 * ignore it. 364 * ignore it.
365 *
366 * @see eio_file_stat_ls()
367 * @see eio_dir_direct_ls()
368 * @see eina_file_stat_ls()
369 * @see ecore_thread_feedback_run()
325 */ 370 */
326EAPI Eio_File *eio_dir_stat_ls(const char *dir, 371EAPI Eio_File *eio_dir_stat_ls(const char *dir,
327 Eio_Filter_Direct_Cb filter_cb, 372 Eio_Filter_Direct_Cb filter_cb,
@@ -341,17 +386,22 @@ EAPI Eio_File *eio_dir_stat_ls(const char *dir,
341 * @return A reference to the I/O operation. 386 * @return A reference to the I/O operation.
342 * 387 *
343 * eio_dir_direct_ls() runs eina_file_direct_ls() recursively in a separate thread using 388 * eio_dir_direct_ls() runs eina_file_direct_ls() recursively in a separate thread using
344 * ecore_thread_feedback_run. This prevents any blocking in your apps. 389 * ecore_thread_feedback_run(). This prevents any blocking in your apps.
345 * Every file will be passed to the filter_cb, so it's your job to decide if you 390 * Every file will be passed to the filter_cb, so it's your job to decide if you
346 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to 391 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to
347 * the main_cb or EINA_FALSE to ignore it. 392 * the main_cb or EINA_FALSE to ignore it.
393 *
394 * @see eio_file_direct_ls()
395 * @see eio_dir_stat_ls()
396 * @see eina_file_direct_ls()
397 * @see ecore_thread_feedback_run()
348 */ 398 */
349EAPI Eio_File *eio_dir_direct_ls(const char *dir, 399EAPI Eio_File *eio_dir_direct_ls(const char *dir,
350 Eio_Filter_Dir_Cb filter_cb, 400 Eio_Filter_Dir_Cb filter_cb,
351 Eio_Main_Direct_Cb main_cb, 401 Eio_Main_Direct_Cb main_cb,
352 Eio_Done_Cb done_cb, 402 Eio_Done_Cb done_cb,
353 Eio_Error_Cb error_cb, 403 Eio_Error_Cb error_cb,
354 const void *data); 404 const void *data);
355 405
356/** 406/**
357 * @brief Stat a file/directory. 407 * @brief Stat a file/directory.
@@ -364,9 +414,25 @@ EAPI Eio_File *eio_dir_direct_ls(const char *dir,
364 * eio_file_direct_stat calls stat in another thread. This prevents any blocking in your apps. 414 * eio_file_direct_stat calls stat in another thread. This prevents any blocking in your apps.
365 */ 415 */
366EAPI Eio_File *eio_file_direct_stat(const char *path, 416EAPI Eio_File *eio_file_direct_stat(const char *path,
367 Eio_Stat_Cb done_cb, 417 Eio_Stat_Cb done_cb,
368 Eio_Error_Cb error_cb, 418 Eio_Error_Cb error_cb,
369 const void *data); 419 const void *data);
420
421/**
422 * @}
423 */
424
425/**
426 * @defgroup Eio_Management Eio file management API.
427 *
428 * @brief A set of function to manage file asynchronously.
429 *
430 * The function provided by this API are the one useful for any
431 * file manager. Like moving or copying a file, unlinking it, changing
432 * it's access right, ...
433 *
434 * @{
435 */
370 436
371/** 437/**
372 * @brief Change rights of a path. 438 * @brief Change rights of a path.
@@ -417,9 +483,9 @@ EAPI Eio_File *eio_file_chown(const char *path,
417 * This function will erase a file. 483 * This function will erase a file.
418 */ 484 */
419EAPI Eio_File *eio_file_unlink(const char *path, 485EAPI Eio_File *eio_file_unlink(const char *path,
420 Eio_Done_Cb done_cb, 486 Eio_Done_Cb done_cb,
421 Eio_Error_Cb error_cb, 487 Eio_Error_Cb error_cb,
422 const void *data); 488 const void *data);
423 489
424/** 490/**
425 * @brief Create a new directory. 491 * @brief Create a new directory.
@@ -433,10 +499,10 @@ EAPI Eio_File *eio_file_unlink(const char *path,
433 * Creates a new directory using the mode provided. 499 * Creates a new directory using the mode provided.
434 */ 500 */
435EAPI Eio_File *eio_file_mkdir(const char *path, 501EAPI Eio_File *eio_file_mkdir(const char *path,
436 mode_t mode, 502 mode_t mode,
437 Eio_Done_Cb done_cb, 503 Eio_Done_Cb done_cb,
438 Eio_Error_Cb error_cb, 504 Eio_Error_Cb error_cb,
439 const void *data); 505 const void *data);
440 506
441/** 507/**
442 * @brief Move a file asynchronously 508 * @brief Move a file asynchronously
@@ -455,11 +521,11 @@ EAPI Eio_File *eio_file_mkdir(const char *path,
455 * access rights, but not user/group identification. 521 * access rights, but not user/group identification.
456 */ 522 */
457EAPI Eio_File *eio_file_move(const char *source, 523EAPI Eio_File *eio_file_move(const char *source,
458 const char *dest, 524 const char *dest,
459 Eio_Progress_Cb progress_cb, 525 Eio_Progress_Cb progress_cb,
460 Eio_Done_Cb done_cb, 526 Eio_Done_Cb done_cb,
461 Eio_Error_Cb error_cb, 527 Eio_Error_Cb error_cb,
462 const void *data); 528 const void *data);
463 529
464/** 530/**
465 * @brief Copy a file asynchronously 531 * @brief Copy a file asynchronously
@@ -477,11 +543,11 @@ EAPI Eio_File *eio_file_move(const char *source,
477 * access rights, but not user/group identification. 543 * access rights, but not user/group identification.
478 */ 544 */
479EAPI Eio_File *eio_file_copy(const char *source, 545EAPI Eio_File *eio_file_copy(const char *source,
480 const char *dest, 546 const char *dest,
481 Eio_Progress_Cb progress_cb, 547 Eio_Progress_Cb progress_cb,
482 Eio_Done_Cb done_cb, 548 Eio_Done_Cb done_cb,
483 Eio_Error_Cb error_cb, 549 Eio_Error_Cb error_cb,
484 const void *data); 550 const void *data);
485 551
486/** 552/**
487 * @brief Move a directory and its content asynchronously 553 * @brief Move a directory and its content asynchronously
@@ -507,12 +573,12 @@ EAPI Eio_File *eio_file_copy(const char *source,
507 * @note if a rename occurs, the filter callback will not be called. 573 * @note if a rename occurs, the filter callback will not be called.
508 */ 574 */
509EAPI Eio_File *eio_dir_move(const char *source, 575EAPI Eio_File *eio_dir_move(const char *source,
510 const char *dest, 576 const char *dest,
511 Eio_Filter_Direct_Cb filter_cb, 577 Eio_Filter_Direct_Cb filter_cb,
512 Eio_Progress_Cb progress_cb, 578 Eio_Progress_Cb progress_cb,
513 Eio_Done_Cb done_cb, 579 Eio_Done_Cb done_cb,
514 Eio_Error_Cb error_cb, 580 Eio_Error_Cb error_cb,
515 const void *data); 581 const void *data);
516 582
517/** 583/**
518 * @brief Copy a directory and its content asynchronously 584 * @brief Copy a directory and its content asynchronously
@@ -535,12 +601,12 @@ EAPI Eio_File *eio_dir_move(const char *source,
535 * the main_cb or EINA_FALSE to ignore it. 601 * the main_cb or EINA_FALSE to ignore it.
536 */ 602 */
537EAPI Eio_File *eio_dir_copy(const char *source, 603EAPI Eio_File *eio_dir_copy(const char *source,
538 const char *dest, 604 const char *dest,
539 Eio_Filter_Direct_Cb filter_cb, 605 Eio_Filter_Direct_Cb filter_cb,
540 Eio_Progress_Cb progress_cb, 606 Eio_Progress_Cb progress_cb,
541 Eio_Done_Cb done_cb, 607 Eio_Done_Cb done_cb,
542 Eio_Error_Cb error_cb, 608 Eio_Error_Cb error_cb,
543 const void *data); 609 const void *data);
544 610
545/** 611/**
546 * @brief Remove a directory and its content asynchronously 612 * @brief Remove a directory and its content asynchronously
@@ -561,15 +627,14 @@ EAPI Eio_File *eio_dir_copy(const char *source,
561 */ 627 */
562EAPI Eio_File *eio_dir_unlink(const char *path, 628EAPI Eio_File *eio_dir_unlink(const char *path,
563 Eio_Filter_Direct_Cb filter_cb, 629 Eio_Filter_Direct_Cb filter_cb,
564 Eio_Progress_Cb progress_cb, 630 Eio_Progress_Cb progress_cb,
565 Eio_Done_Cb done_cb, 631 Eio_Done_Cb done_cb,
566 Eio_Error_Cb error_cb, 632 Eio_Error_Cb error_cb,
567 const void *data); 633 const void *data);
568/** 634/**
569 * @} 635 * @}
570 */ 636 */
571 637
572
573/** 638/**
574 * @defgroup Eio_Xattr Eio manipulation of eXtended attribute. 639 * @defgroup Eio_Xattr Eio manipulation of eXtended attribute.
575 * @ingroup Eio 640 * @ingroup Eio