1 #ifdef __cplusplus 2 extern "C" { 3 #endif 4 5 /** 6 * @typedef Eio_Version 7 * Represents the current version of EIO 8 */ 9 typedef struct _Eio_Version 10 { 11 int major; /**< Major version number */ 12 int minor; /**< Minor version number */ 13 int micro; /**< Micro version number */ 14 int revision; /**< Revision number */ 15 } Eio_Version; 16 17 /** 18 * Eio Version Information 19 * @ingroup Eio 20 */ 21 EAPI extern Eio_Version *eio_version; 22 23 /** 24 * @file 25 * @brief Eio asynchronous input/output library 26 * 27 * These routines are used for Eio. 28 */ 29 30 /** 31 * @page eio_main Eio 32 * 33 * @date 2012 (created) 34 * 35 * @section eio_toc Table of Contents 36 * 37 * @li @ref eio_main_intro 38 * @li @ref eio_main_compiling 39 * @li @ref eio_main_next_steps 40 * @li @ref eio_main_intro_example 41 * 42 * @section eio_main_intro Introduction 43 * 44 * The Eio library is a library that implements an API for asynchronous 45 * input/output operation. Most operations are done in a separate thread 46 * to prevent lock. See @ref Eio. Some helper to work on data 47 * received in Eio callback are also provided see @ref Eio_Helper. 48 * It is also possible to work asynchronously on Eina_File with @ref Eio_Map 49 * or on Eet_File with @ref Eio_Eet. It comes with way to manipulate 50 * eXtended attribute asynchronous with @ref Eio_Xattr. 51 * 52 * This library is cross-platform and can be compiled and used on 53 * Linux, BSD, Opensolaris and Windows (XP and CE). It is heavily 54 * based on @ref Ecore_Main_Loop_Group. 55 * 56 * @section eio_main_compiling How to compile 57 * 58 * Eio is a library your application links to. The procedure for this is 59 * very simple. You simply have to compile your application with the 60 * appropriate compiler flags that the @c pkg-config script outputs. For 61 * example: 62 * 63 * Compiling C or C++ files into object files: 64 * 65 * @verbatim 66 gcc -c -o main.o main.c `pkg-config --cflags eio` 67 @endverbatim 68 * 69 * Linking object files into a binary executable: 70 * 71 * @verbatim 72 gcc -o my_application main.o `pkg-config --libs eio` 73 @endverbatim 74 * 75 * See @ref pkgconfig 76 * 77 * @section eio_main_next_steps Next Steps 78 * 79 * After you understand what Eio is and installed it on your system 80 * you should proceed understand the programming interface. 81 * 82 * Recommended reading: 83 * 84 * @li @ref Eio_Helper for common functions and library initialization. 85 * @li @ref Eio_List for listing files asynchronous. 86 * @li @ref Eio_Management for anyone who want to do a file manager (copy, rm, ...). 87 * @li @ref Eio_Map to manipulate files asynchronously (mmap). 88 * @li @ref Eio_Xattr to access file extended attributes (xattr). 89 * @li @ref Eio_Monitor to monitor for file changes (inotify). 90 * @li @ref Eio_Eet to access Eet files asynchronously. 91 * 92 * @section eio_main_intro_example Introductory Example 93 * 94 * @include eio_file_ls.c 95 * 96 * More examples can be found at @ref eio_examples. 97 * 98 */ 99 100 /** 101 * @enum _Eio_File_Op 102 * 103 * @brief Input/Output operations on files. 104 * 105 * This enum represents the operations that can be done. 106 */ 107 enum _Eio_File_Op 108 { 109 EIO_FILE_COPY, /**< I/O operation is about a specific file copy */ 110 EIO_FILE_MOVE, /**< I/O operation is about a specific file move */ 111 EIO_DIR_COPY, /**< I/O operation is about a specific directory copy */ 112 EIO_DIR_MOVE, /**< I/O operation is about a specific directory move */ 113 /** I/O operation is about destroying a path: 114 * source will point to base path to be destroyed, 115 * and dest will point to to path destroyed by this I/O 116 */ 117 EIO_UNLINK, 118 EIO_FILE_GETPWNAM, /**< I/O operation is trying to get uid from user name */ 119 EIO_FILE_GETGRNAM /**< I/O operation is trying to get gid from user name */ 120 }; 121 122 /** 123 * @typedef Eio_File_Op 124 * Input/Output operations on files. 125 */ 126 typedef enum _Eio_File_Op Eio_File_Op; 127 128 /** 129 * @defgroup Eio_List Eio file listing API 130 * @ingroup Eio 131 * 132 * @brief This functions helps list files asynchronously. 133 * 134 * This set of functions work on top of Eina_File and Ecore_Thread 135 * to list files under various condition. 136 * 137 * @{ 138 */ 139 140 /** 141 * @typedef Eio_Progress 142 * Progress information on a specific operation. 143 */ 144 typedef struct _Eio_Progress Eio_Progress; 145 146 typedef Eina_Bool (*Eio_Filter_Cb)(void *data, Eio_File *handler, const char *file); 147 typedef void (*Eio_Main_Cb)(void *data, Eio_File *handler, const char *file); 148 149 typedef Eina_Bool (*Eio_Filter_Dir_Cb)(void *data, Eio_File *handler, Eina_File_Direct_Info *info); 150 typedef void (*Eio_Main_Direct_Cb)(void *data, Eio_File *handler, const Eina_File_Direct_Info *info); 151 152 typedef void (*Eio_Stat_Cb)(void *data, Eio_File *handler, const Eina_Stat *stat); 153 typedef void (*Eio_Progress_Cb)(void *data, Eio_File *handler, const Eio_Progress *info); 154 155 typedef void (*Eio_Eet_Open_Cb)(void *data, Eio_File *handler, Eet_File *file); 156 typedef void (*Eio_Open_Cb)(void *data, Eio_File *handler, Eina_File *file); 157 typedef Eina_Bool (*Eio_Filter_Map_Cb)(void *data, Eio_File *handler, void *map, size_t length); 158 typedef void (*Eio_Map_Cb)(void *data, Eio_File *handler, void *map, size_t length); 159 160 typedef void (*Eio_Done_Data_Cb)(void *data, Eio_File *handler, const char *read_data, unsigned int size); 161 typedef void (*Eio_Done_String_Cb)(void *data, Eio_File *handler, const char *xattr_string); 162 typedef void (*Eio_Done_Double_Cb)(void *data, Eio_File *handler, double xattr_double); 163 typedef void (*Eio_Done_Int_Cb)(void *data, Eio_File *handler, int i); 164 165 typedef void (*Eio_Done_ERead_Cb)(void *data, Eio_File *handler, void *decoded); 166 typedef void (*Eio_Done_Read_Cb)(void *data, Eio_File *handler, void *read_data, unsigned int size); 167 typedef void (*Eio_Done_Cb)(void *data, Eio_File *handler); 168 typedef void (*Eio_Error_Cb)(void *data, Eio_File *handler, int error); 169 typedef void (*Eio_Eet_Error_Cb)(void *data, Eio_File *handler, Eet_Error err); 170 171 /** 172 * @struct _Eio_Progress 173 * @brief Represents the current progress of the operation. 174 */ 175 struct _Eio_Progress 176 { 177 Eio_File_Op op; /**< I/O type */ 178 179 long long current; /**< Current step in the I/O operation */ 180 long long max; /**< Number of total steps to complete this I/O */ 181 float percent; /**< Percent done for the I/O operation */ 182 183 const char *source; /**< source of the I/O operation */ 184 const char *dest; /**< target of the I/O operation */ 185 }; 186 187 /** 188 * @brief List contents of a directory without locking your app. 189 * @param dir The directory to list. 190 * @param filter_cb Callback used to decide if the file will be passed to main_cb 191 * @param main_cb Callback called for each listed file if it was not filtered. 192 * @param done_cb Callback called when the ls operation is done. 193 * @param error_cb Callback called when either the directory could not be opened or the operation has been canceled. 194 * @param data Unmodified user data passed to callbacks 195 * @return A reference to the I/O operation. 196 * 197 * This function is responsible for listing the content of a directory without blocking your application. 198 * It's equivalent to the "ls" shell command. Every file will be passed to the 199 * filter_cb, so it's your job to decide if you want to pass the file to the 200 * main_cb or not. Return EINA_TRUE to pass it to the main_cb or EINA_FALSE to 201 * ignore it. It runs eina_file_ls() in a separate thread using 202 * ecore_thread_feedback_run(). 203 * 204 * @see eina_file_ls() 205 * @see ecore_thread_feedback_run() 206 * @see eio_file_direct_ls() 207 * @see eio_file_stat_ls() 208 */ 209 EAPI Eio_File *eio_file_ls(const char *dir, 210 Eio_Filter_Cb filter_cb, 211 Eio_Main_Cb main_cb, 212 Eio_Done_Cb done_cb, 213 Eio_Error_Cb error_cb, 214 const void *data); 215 216 /** 217 * @brief List contents of a directory without locking your app. 218 * @param dir The directory to list. 219 * @param filter_cb Callback used to decide if the file will be passed to main_cb 220 * @param main_cb Callback called from the main loop for each accepted file (not filtered). 221 * @param done_cb Callback called from the main loop after the contents of the directory has been listed. 222 * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. 223 * @param data Unmodified user data passed to callbacks 224 * @return A reference to the I/O operation. 225 * 226 * eio_file_direct_ls() runs eina_file_direct_ls() in a separate thread using 227 * ecore_thread_feedback_run(). This prevents any blocking in your apps. 228 * Every file will be passed to the filter_cb, so it's your job to decide if you 229 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to 230 * the main_cb or EINA_FALSE to ignore it. 231 * 232 * @warning If readdir_r doesn't contain file type information, file type is 233 * EINA_FILE_UNKNOWN. 234 * 235 * @note The iterator walks over '.' and '..' without returning them. 236 * @note The difference between this function and eina_file_stat_ls() is that 237 * it may not get the file type information however it is likely to be 238 * faster. 239 * 240 * @see eio_file_stat_ls() 241 * @see eina_file_direct_ls() 242 * @see ecore_thread_feedback_run() 243 */ 244 EAPI Eio_File *eio_file_direct_ls(const char *dir, 245 Eio_Filter_Direct_Cb filter_cb, 246 Eio_Main_Direct_Cb main_cb, 247 Eio_Done_Cb done_cb, 248 Eio_Error_Cb error_cb, 249 const void *data); 250 251 /** 252 * @brief List content of a directory without locking your app. 253 * @param dir The directory to list. 254 * @param filter_cb Callback used to decide if the file will be passed to main_cb 255 * @param main_cb Callback called from the main loop for each accepted file (not filtered). 256 * @param done_cb Callback called from the main loop after the contents of the directory has been listed. 257 * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. 258 * @param data Unmodified user data passed to callbacks 259 * @return A reference to the I/O operation. 260 * 261 * Every file will be passed to the filter_cb, so it's your job to decide if you 262 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to 263 * the main_cb or EINA_FALSE to ignore it. eio_file_stat_ls() run eina_file_stat_ls() 264 * in a separate thread using ecore_thread_feedback_run(). 265 * 266 * @note The iterator walks over '.' and '..' without returning them. 267 * @note The difference between this function and eio_file_direct_ls() is that 268 * it guarantees the file type information to be correct by incurring a 269 * possible performance penalty. 270 * 271 * @see eio_file_stat_ls() 272 * @see eina_file_stat_ls() 273 * @see ecore_thread_feedback_run() 274 */ 275 EAPI Eio_File *eio_file_stat_ls(const char *dir, 276 Eio_Filter_Direct_Cb filter_cb, 277 Eio_Main_Direct_Cb main_cb, 278 Eio_Done_Cb done_cb, 279 Eio_Error_Cb error_cb, 280 const void *data); 281 282 /** 283 * @brief List the content of a directory and all its sub-content asynchronously 284 * @param dir The directory to list. 285 * @param filter_cb Callback used to decide if the file will be passed to main_cb 286 * @param main_cb Callback called from the main loop for each accepted file (not filtered). 287 * @param done_cb Callback called from the main loop after the contents of the directory has been listed. 288 * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. 289 * @param data Unmodified user data passed to callbacks 290 * @return A reference to the I/O operation. 291 * 292 * eio_dir_stat_ls() runs eina_file_stat_ls() recursively in a separate thread using 293 * ecore_thread_feedback_run(). This prevents any blocking in your apps. 294 * Every file will be passed to the 295 * filter_cb, so it's your job to decide if you want to pass the file to the 296 * main_cb or not. Return EINA_TRUE to pass it to the main_cb or EINA_FALSE to 297 * ignore it. 298 * 299 * @see eio_file_stat_ls() 300 * @see eio_dir_direct_ls() 301 * @see eina_file_stat_ls() 302 * @see ecore_thread_feedback_run() 303 */ 304 EAPI Eio_File *eio_dir_stat_ls(const char *dir, 305 Eio_Filter_Direct_Cb filter_cb, 306 Eio_Main_Direct_Cb main_cb, 307 Eio_Done_Cb done_cb, 308 Eio_Error_Cb error_cb, 309 const void *data); 310 311 /** 312 * @brief List the content of a directory and all its sub-content asynchronously 313 * @param dir The directory to list. 314 * @param filter_cb Callback used to decide if the file will be passed to main_cb 315 * @param main_cb Callback called from the main loop for each accepted file (not filtered). 316 * @param done_cb Callback called from the main loop after the contents of the directory has been listed. 317 * @param error_cb Callback called from the main loop when either the directory could not be opened or the operation has been canceled. 318 * @param data Unmodified user data passed to callbacks 319 * @return A reference to the I/O operation. 320 * 321 * eio_dir_direct_ls() runs eina_file_direct_ls() recursively in a separate thread using 322 * ecore_thread_feedback_run(). This prevents any blocking in your apps. 323 * Every file will be passed to the filter_cb, so it's your job to decide if you 324 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to 325 * the main_cb or EINA_FALSE to ignore it. 326 * 327 * @see eio_file_direct_ls() 328 * @see eio_dir_stat_ls() 329 * @see eina_file_direct_ls() 330 * @see ecore_thread_feedback_run() 331 */ 332 EAPI Eio_File *eio_dir_direct_ls(const char *dir, 333 Eio_Filter_Dir_Cb filter_cb, 334 Eio_Main_Direct_Cb main_cb, 335 Eio_Done_Cb done_cb, 336 Eio_Error_Cb error_cb, 337 const void *data); 338 339 /** 340 * @brief Stat a file/directory. 341 * @param path The path to stat. 342 * @param done_cb Callback called from the main loop when stat was successfully called. 343 * @param error_cb Callback called from the main loop when stat failed or has been canceled. 344 * @param data Unmodified user data passed to callbacks 345 * @return A reference to the I/O operation. 346 * 347 * eio_file_direct_stat calls stat in another thread. This prevents any blocking in your apps. 348 */ 349 EAPI Eio_File *eio_file_direct_stat(const char *path, 350 Eio_Stat_Cb done_cb, 351 Eio_Error_Cb error_cb, 352 const void *data); 353 354 /** 355 * @} 356 */ 357 358 /** 359 * @defgroup Eio_Management Eio file management API. 360 * @ingroup Eio 361 * 362 * @brief A set of function to manage file asynchronously. 363 * 364 * The function provided by this API are the one useful for any 365 * file manager. Like moving or copying a file, unlinking it, changing 366 * it's access right, ... 367 * 368 * @{ 369 */ 370 371 /** 372 * @brief Change rights of a path. 373 * @param path The directory path to change access rights. 374 * @param mode The permission to set, follow (mode & ~umask & 0777). 375 * @param done_cb Callback called when the operation is completed. 376 * @param error_cb Callback called from if something goes wrong. 377 * @param data Unmodified user data passed to callbacks. 378 * @return A reference to the I/O operation. 379 * 380 * Set a new permission of a path changing it to the mode passed as argument. 381 * It's equivalent to the chmod command. 382 */ 383 EAPI Eio_File *eio_file_chmod(const char *path, 384 mode_t mode, 385 Eio_Done_Cb done_cb, 386 Eio_Error_Cb error_cb, 387 const void *data); 388 389 /** 390 * @brief Change owner of a path. 391 * @param path The directory path to change owner. 392 * @param user The new user to set (can be NULL). 393 * @param group The new group to set (can be NULL). 394 * @param done_cb Callback called when the operation is completed. 395 * @param error_cb Callback called from if something goes wrong. 396 * @param data Unmodified user data passed to callbacks 397 * @return A reference to the I/O operation. 398 * 399 * This function will change the owner of a path, setting it to the user and 400 * group passed as argument. It's equivalent to the chown shell command. 401 * 402 * @note Some platforms (including Windows) do not support chown(). In that 403 * case, this function returns @c NULL. 404 */ 405 EAPI Eio_File *eio_file_chown(const char *path, 406 const char *user, 407 const char *group, 408 Eio_Done_Cb done_cb, 409 Eio_Error_Cb error_cb, 410 const void *data); 411 412 /** 413 * @brief Unlink a file/directory. 414 * @param path The path to unlink. 415 * @param done_cb Callback called when the operation is completed. 416 * @param error_cb Callback called from if something goes wrong. 417 * @param data Unmodified user data passed to callbacks. 418 * @return A reference to the I/O operation. 419 * 420 * This function will erase a file. 421 */ 422 EAPI Eio_File *eio_file_unlink(const char *path, 423 Eio_Done_Cb done_cb, 424 Eio_Error_Cb error_cb, 425 const void *data); 426 427 /** 428 * @brief Create a new directory. 429 * @param path The directory path to create. 430 * @param mode The permission to set, follow (mode & ~umask & 0777). 431 * @param done_cb Callback called when the operation is completed. 432 * @param error_cb Callback called from if something goes wrong. 433 * @param data Unmodified user data passed to callbacks 434 * @return A reference to the I/O operation. 435 * 436 * Creates a new directory using the mode provided. 437 */ 438 EAPI Eio_File *eio_file_mkdir(const char *path, 439 mode_t mode, 440 Eio_Done_Cb done_cb, 441 Eio_Error_Cb error_cb, 442 const void *data); 443 444 /** 445 * @brief Move a file asynchronously 446 * @param source Should be the name of the file to move the data from. 447 * @param dest Should be the name of the file to move the data to. 448 * @param progress_cb Callback called to know the progress of the move. 449 * @param done_cb Callback called when the move is done. 450 * @param error_cb Callback called when something goes wrong. 451 * @param data Unmodified user data passed to callbacks 452 * @return A reference to the I/O operation. 453 * 454 * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation 455 * 456 * This function will copy a file from source to dest. It will try to use splice 457 * if possible, if not it will fallback to mmap/write. It will try to preserve 458 * access rights, but not user/group identification. 459 */ 460 EAPI Eio_File *eio_file_move(const char *source, 461 const char *dest, 462 Eio_Progress_Cb progress_cb, 463 Eio_Done_Cb done_cb, 464 Eio_Error_Cb error_cb, 465 const void *data); 466 467 /** 468 * @brief Copy a file asynchronously 469 * @param source Should be the name of the file to copy the data from. 470 * @param dest Should be the name of the file to copy the data to. 471 * @param progress_cb Callback called to know the progress of the copy. 472 * @param done_cb Callback called when the copy is done. 473 * @param error_cb Callback called when something goes wrong. 474 * @param data Unmodified user data passed to callbacks 475 * 476 * @return an Eio_File pointer, handler to the copy operation, can be used to cancel the operation 477 * 478 * This function will copy a file from source to dest. It will try to use splice 479 * if possible, if not it will fallback to mmap/write. It will try to preserve 480 * access rights, but not user/group identification. 481 */ 482 EAPI Eio_File *eio_file_copy(const char *source, 483 const char *dest, 484 Eio_Progress_Cb progress_cb, 485 Eio_Done_Cb done_cb, 486 Eio_Error_Cb error_cb, 487 const void *data); 488 489 /** 490 * @brief Move a directory and its content asynchronously 491 * @param source Should be the name of the directory to copy the data from. 492 * @param dest Should be the name of the directory to copy the data to. 493 * @param filter_cb Possible to deny the move of some files/directories. 494 * @param progress_cb Callback called to know the progress of the copy. 495 * @param done_cb Callback called when the copy is done. 496 * @param error_cb Callback called when something goes wrong. 497 * @param data Unmodified user data passed to callbacks 498 * @return A reference to the I/O operation. 499 * 500 * @return an Eio_File pointer, handler to the move operation, can be used to cancel the operation 501 * 502 * This function will move a directory and all its content from source to dest. 503 * It will try first to rename the directory, if not it will try to use splice 504 * if possible, if not it will fallback to mmap/write. 505 * It will try to preserve access rights, but not user/group identity. 506 * Every file will be passed to the filter_cb, so it's your job to decide if you 507 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to 508 * the main_cb or EINA_FALSE to ignore it. 509 * 510 * @note if a rename occurs, the filter callback will not be called. 511 */ 512 EAPI Eio_File *eio_dir_move(const char *source, 513 const char *dest, 514 Eio_Filter_Direct_Cb filter_cb, 515 Eio_Progress_Cb progress_cb, 516 Eio_Done_Cb done_cb, 517 Eio_Error_Cb error_cb, 518 const void *data); 519 520 /** 521 * @brief Copy a directory and its content asynchronously 522 * @param source Should be the name of the directory to copy the data from. 523 * @param dest Should be the name of the directory to copy the data to. 524 * @param filter_cb Possible to deny the move of some files/directories. 525 * @param progress_cb Callback called to know the progress of the copy. 526 * @param done_cb Callback called when the copy is done. 527 * @param error_cb Callback called when something goes wrong. 528 * @param data Unmodified user data passed to callbacks 529 * @return A reference to the I/O operation. 530 * 531 * @return an Eio_File pointer, handler to the copy operation, can be used to cancel the operation 532 * 533 * This function will copy a directory and all its content from source to dest. 534 * It will try to use splice if possible, if not it will fallback to mmap/write. 535 * It will try to preserve access rights, but not user/group identity. 536 * Every file will be passed to the filter_cb, so it's your job to decide if you 537 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to 538 * the main_cb or EINA_FALSE to ignore it. 539 */ 540 EAPI Eio_File *eio_dir_copy(const char *source, 541 const char *dest, 542 Eio_Filter_Direct_Cb filter_cb, 543 Eio_Progress_Cb progress_cb, 544 Eio_Done_Cb done_cb, 545 Eio_Error_Cb error_cb, 546 const void *data); 547 548 /** 549 * @brief Remove a directory and its content asynchronously 550 * @param path Should be the name of the directory to destroy. 551 * @param filter_cb Possible to deny the move of some files/directories. 552 * @param progress_cb Callback called to know the progress of the copy. 553 * @param done_cb Callback called when the copy is done. 554 * @param error_cb Callback called when something goes wrong. 555 * @param data Unmodified user data passed to callbacks 556 * @return A reference to the I/O operation. 557 * 558 * @return an Eio_File pointer, handler to the unlink operation, can be used to cancel the operation 559 * 560 * This function will remove a directory and all its content. 561 * Every file will be passed to the filter_cb, so it's your job to decide if you 562 * want to pass the file to the main_cb or not. Return EINA_TRUE to pass it to 563 * the main_cb or EINA_FALSE to ignore it. 564 */ 565 EAPI Eio_File *eio_dir_unlink(const char *path, 566 Eio_Filter_Direct_Cb filter_cb, 567 Eio_Progress_Cb progress_cb, 568 Eio_Done_Cb done_cb, 569 Eio_Error_Cb error_cb, 570 const void *data); 571 /** 572 * @} 573 */ 574 575 /** 576 * @defgroup Eio_Xattr Eio manipulation of eXtended attribute. 577 * @ingroup Eio 578 * 579 * @brief A set of function to manipulate data associated with a specific file 580 * 581 * The functions provided by this API are responsible to manage Extended 582 * attribute files. Like file authors, character encoding, checksum, etc. 583 * @{ 584 */ 585 586 /** 587 * @brief Asynchronously list all eXtended attribute 588 * @param path The path to get the eXtended attribute from. 589 * @param filter_cb Callback called in the thread to validate the eXtended attribute. 590 * @param main_cb Callback called in the main loop for each accepted eXtended attribute. 591 * @param done_cb Callback called in the main loop when the all the eXtended attribute have been listed. 592 * @param error_cb Callback called in the main loop when something goes wrong during the listing of the eXtended attribute. 593 * @param data Unmodified user data passed to callbacks 594 * @return A reference to the I/O operation. 595 */ 596 EAPI Eio_File *eio_file_xattr(const char *path, 597 Eio_Filter_Cb filter_cb, 598 Eio_Main_Cb main_cb, 599 Eio_Done_Cb done_cb, 600 Eio_Error_Cb error_cb, 601 const void *data); 602 603 /** 604 * @brief Define an extended attribute on a file/directory. 605 * @param path The path to set the attribute on. 606 * @param attribute The name of the attribute to define. 607 * @param xattr_int The value to link the attribute with. 608 * @param flags Whether to insert, replace or create the attribute. 609 * @param done_cb The callback called from the main loop when setxattr succeeded. 610 * @param error_cb The callback called from the main loop when setxattr failed. 611 * @param data Unmodified user data passed to callbacks 612 * @return A reference to the I/O operation. 613 * 614 * eio_file_xattr_int_set calls eina_xattr_int_set from another thread. This prevents blocking in your apps. If 615 * the writing succeeded, the done_cb will be called even if a cancel was requested, but came too late. 616 */ 617 EAPI Eio_File *eio_file_xattr_int_set(const char *path, 618 const char *attribute, 619 int xattr_int, 620 Eina_Xattr_Flags flags, 621 Eio_Done_Cb done_cb, 622 Eio_Error_Cb error_cb, 623 const void *data); 624 625 /** 626 * @brief Define an extended attribute on a file/directory. 627 * @param path The path to set the attribute on. 628 * @param attribute The name of the attribute to define. 629 * @param xattr_double The value to link the attribute with. 630 * @param flags Whether to insert, replace or create the attribute. 631 * @param done_cb The callback called from the main loop when setxattr succeeded. 632 * @param error_cb The callback called from the main loop when setxattr failed. 633 * @param data Unmodified user data passed to callbacks 634 * @return A reference to the I/O operation. 635 * 636 * eio_file_xattr_double_set calls eina_xattr_double_set from another thread. This prevents blocking in your apps. If 637 * the writing succeeded, the done_cb will be called even if a cancel was requested, but came too late. 638 */ 639 EAPI Eio_File *eio_file_xattr_double_set(const char *path, 640 const char *attribute, 641 double xattr_double, 642 Eina_Xattr_Flags flags, 643 Eio_Done_Cb done_cb, 644 Eio_Error_Cb error_cb, 645 const void *data); 646 /** 647 * @brief Define a string extended attribute on a file/directory. 648 * @param path The path to set the attribute on. 649 * @param attribute The name of the attribute to define. 650 * @param xattr_string The string to link the attribute with. 651 * @param flags Whether to insert, replace or create the attribute. 652 * @param done_cb The callback called from the main loop when setxattr succeeded. 653 * @param error_cb The callback called from the main loop when setxattr failed. 654 * @param data Unmodified user data passed to callbacks 655 * @return A reference to the I/O operation. 656 * 657 * eio_file_xattr_string_set calls eina_xattr_string_set from another thread. This prevents blocking in your apps. If 658 * the writing succeeded, the done_cb will be called even if a cancel was requested, but came too late. 659 */ 660 EAPI Eio_File *eio_file_xattr_string_set(const char *path, 661 const char *attribute, 662 const char *xattr_string, 663 Eina_Xattr_Flags flags, 664 Eio_Done_Cb done_cb, 665 Eio_Error_Cb error_cb, 666 const void *data); 667 /** 668 * @brief Define an extended attribute on a file/directory. 669 * @param path The path to set the attribute on. 670 * @param attribute The name of the attribute to define. 671 * @param xattr_data The data to link the attribute with. 672 * @param xattr_size The size of the data to set. 673 * @param flags Whether to insert, replace or create the attribute. 674 * @param done_cb The callback called from the main loop when setxattr succeeded. 675 * @param error_cb The callback called from the main loop when setxattr failed. 676 * @param data Unmodified user data passed to callbacks 677 * @return A reference to the I/O operation. 678 * 679 * eio_file_xattr_set calls setxattr from another thread. This prevents blocking in your apps. If 680 * the writing succeeded, the done_cb will be called even if a cancel was requested, but came too late. 681 */ 682 EAPI Eio_File *eio_file_xattr_set(const char *path, 683 const char *attribute, 684 const char *xattr_data, 685 unsigned int xattr_size, 686 Eina_Xattr_Flags flags, 687 Eio_Done_Cb done_cb, 688 Eio_Error_Cb error_cb, 689 const void *data); 690 691 /** 692 * @brief Retrieve the extended attribute of a file/directory. 693 * @param path The path to retrieve the extended attribute from. 694 * @param attribute The name of the attribute to retrieve. 695 * @param done_cb Callback called from the main loop when getxattr succeeded. 696 * @param error_cb Callback called from the main loop when getxattr failed or has been canceled. 697 * @param data Unmodified user data passed to callbacks 698 * @return A reference to the I/O operation. 699 * 700 * eio_file_xattr_get calls getxattr from another thread. This prevents blocking in your apps. 701 */ 702 EAPI Eio_File *eio_file_xattr_get(const char *path, 703 const char *attribute, 704 Eio_Done_Data_Cb done_cb, 705 Eio_Error_Cb error_cb, 706 const void *data); 707 /** 708 * @brief Retrieve a extended attribute of a file/directory. 709 * @param path The path to retrieve the extended attribute from. 710 * @param attribute The name of the attribute to retrieve. 711 * @param done_cb Callback called from the main loop when getxattr succeeded. 712 * @param error_cb Callback called from the main loop when getxattr failed or has been canceled. 713 * @param data Unmodified user data passed to callbacks 714 * @return A reference to the I/O operation. 715 * 716 * eio_file_xattr_int_get calls eina_xattr_int_get from another thread. This prevents blocking in your apps. 717 */ 718 EAPI Eio_File *eio_file_xattr_int_get(const char *path, 719 const char *attribute, 720 Eio_Done_Int_Cb done_cb, 721 Eio_Error_Cb error_cb, 722 const void *data); 723 /** 724 * @brief Retrieve a extended attribute of a file/directory. 725 * @param path The path to retrieve the extended attribute from. 726 * @param attribute The name of the attribute to retrieve. 727 * @param done_cb Callback called from the main loop when getxattr succeeded. 728 * @param error_cb Callback called from the main loop when getxattr failed or has been canceled. 729 * @param data Unmodified user data passed to callbacks 730 * @return A reference to the I/O operation. 731 * 732 * eio_file_xattr_double_get calls eina_xattr_double_get from another thread. This prevents blocking in your apps. 733 */ 734 EAPI Eio_File *eio_file_xattr_double_get(const char *path, 735 const char *attribute, 736 Eio_Done_Double_Cb done_cb, 737 Eio_Error_Cb error_cb, 738 const void *data); 739 /** 740 * @brief Retrieve a string extended attribute of a file/directory. 741 * @param path The path to retrieve the extended attribute from. 742 * @param attribute The name of the attribute to retrieve. 743 * @param done_cb Callback called from the main loop when getxattr succeeded. 744 * @param error_cb Callback called from the main loop when getxattr failed or has been canceled. 745 * @param data Unmodified user data passed to callbacks 746 * @return A reference to the I/O operation. 747 * 748 * eio_file_xattr_string_get calls eina_xattr_string_get from another thread. This prevents blocking in your apps. 749 */ 750 EAPI Eio_File *eio_file_xattr_string_get(const char *path, 751 const char *attribute, 752 Eio_Done_String_Cb done_cb, 753 Eio_Error_Cb error_cb, 754 const void *data); 755 756 /** 757 * @} 758 */ 759 760 /** 761 * @defgroup Eio_Helper Eio Reference helper API 762 * @ingroup Eio 763 * 764 * @brief This are helper provided around core Eio API. 765 * 766 * This set of functions do provide helper to work around data 767 * provided by Eio without the need to look at system header. 768 * 769 * @{ 770 */ 771 772 773 /** 774 * @brief Initialize eio and all its required submodule. 775 * @return the current number of eio users. 776 */ 777 EAPI int eio_init(void); 778 779 /** 780 * @brief Shutdown eio and all its submodule if possible. 781 * @return the number of pending users of eio. 782 */ 783 EAPI int eio_shutdown(void); 784 785 /** 786 * @brief Set the limit to the maximum amount of memory used 787 * @param limit The actual limit to set. 788 * 789 * Eio work by burst, allocating memory in a thread and moving it 790 * back to the main loop. This result in quite some huge memory 791 * usage if the main loop is to slow to cope with the speed of the 792 * thread. By setting this limit, the thread will block until 793 * enough memory has been freed to be below the limit again. 794 * 795 * By default no limit is set and any value < 0 will mean no limit. 796 * 797 * @note You should give at least a reasonable amount of memory or 798 * the thread might stall. 799 * @since 1.10 800 */ 801 EAPI void eio_memory_burst_limit_set(size_t limit); 802 803 /** 804 * @brief Get the actual limit to the maximum amount of memory used 805 * @return The current limit being set. 806 * 807 * @since 1.10 808 * @see eio_memory_burst_limit_set 809 */ 810 EAPI size_t eio_memory_burst_limit_get(void); 811 812 /** 813 * @brief Return the container during EIO operation 814 * @param ls The asynchronous I/O operation to retrieve container from. 815 * @return NULL if not available, a DIRP if it is. 816 * 817 * This is only available and make sense in the thread callback, not in 818 * the mainloop. 819 */ 820 EAPI void *eio_file_container_get(Eio_File *ls); 821 822 /** 823 * @brief Cancel any Eio_File. 824 * @param ls The asynchronous I/O operation to cancel. 825 * @return EINA_FALSE if the destruction is delayed, EINA_TRUE if it's done. 826 * 827 * This will cancel any kind of I/O operation and cleanup the mess. This means 828 * that it could take time to cancel an I/O. 829 */ 830 EAPI Eina_Bool eio_file_cancel(Eio_File *ls); 831 832 /** 833 * @brief Check if an Eio_File operation has been cancelled. 834 * @param ls The asynchronous I/O operation to check. 835 * @return EINA_TRUE if it was canceled, EINA_FALSE other wise. 836 * 837 * In case of an error it also return EINA_TRUE. 838 */ 839 EAPI Eina_Bool eio_file_check(Eio_File *ls); 840 841 /** 842 * @brief Associate data with the current filtered file. 843 * @param ls The Eio_File ls request currently calling the filter callback. 844 * @param key The key to associate data to. 845 * @param data The data to associate the data to. 846 * @param free_cb Optionally a function to call to free the associated data, 847 * @p data is passed as the callback data parameter. If no @p free_cb is provided 848 * the user @p data remains untouched. 849 * @return EINA_TRUE if insertion was fine. 850 * 851 * This function can only be safely called from within the filter callback. 852 * If you don't need to copy the key around you can use @ref eio_file_associate_direct_add 853 */ 854 EAPI Eina_Bool eio_file_associate_add(Eio_File *ls, 855 const char *key, 856 const void *data, Eina_Free_Cb free_cb); 857 858 /** 859 * @brief Associate data with the current filtered file. 860 * @param ls The Eio_File ls request currently calling the filter callback. 861 * @param key The key to associate data to (will not be copied, and the pointer will not be used as long as the file is not notified). 862 * @param data The data to associate the data to. 863 * @param free_cb The function to call to free the associated data, @p free_cb will be called if not specified. 864 * @return EINA_TRUE if insertion was fine. 865 * 866 * This function can only be safely called from within the filter callback. 867 * If you need eio to make a proper copy of the @p key to be safe use 868 * @ref eio_file_associate_add instead. 869 */ 870 EAPI Eina_Bool eio_file_associate_direct_add(Eio_File *ls, 871 const char *key, 872 const void *data, Eina_Free_Cb free_cb); 873 874 /** 875 * @brief Get the data associated during the filter callback inside the main loop 876 * @param ls The Eio_File ls request currently calling the notify callback. 877 * @param key The key pointing to the data to retrieve. 878 * @return the data associated with the key or @p NULL if not found. 879 */ 880 EAPI void *eio_file_associate_find(Eio_File *ls, const char *key); 881 882 /** 883 * @} 884 */ 885 886 /** 887 * 888 */ 889 890 /** 891 * @defgroup Eio_Map Manipulate an Eina_File asynchronously 892 * @ingroup Eio 893 * 894 * @brief This function helps when manipulating a file asynchronously. 895 * 896 * These set of functions work on top of Eina_File and Ecore_Thread to 897 * do basic operations on a file, like opening, closing and mapping a file to 898 * memory. 899 * @{ 900 */ 901 902 /** 903 * @brief Asynchronously open a file. 904 * @param name The file to open. 905 * @param shared If it's a shared memory file. 906 * @param open_cb Callback called in the main loop when the file has been successfully opened. 907 * @param error_cb Callback called in the main loop when the file couldn't be opened. 908 * @param data Unmodified user data passed to callbacks 909 * @return Pointer to the file if successful or NULL otherwise. 910 * 911 */ 912 EAPI Eio_File *eio_file_open(const char *name, Eina_Bool shared, 913 Eio_Open_Cb open_cb, 914 Eio_Error_Cb error_cb, 915 const void *data); 916 917 /** 918 * @brief Asynchronously close a file. 919 * @param f The file to close. 920 * @param done_cb Callback called in the main loop when the file has been successfully closed. 921 * @param error_cb Callback called in the main loop when the file couldn't be closed. 922 * @param data Unmodified user data passed to callbacks 923 * @return Pointer to the file if successful or NULL otherwise. 924 */ 925 EAPI Eio_File *eio_file_close(Eina_File *f, 926 Eio_Done_Cb done_cb, 927 Eio_Error_Cb error_cb, 928 const void *data); 929 930 /** 931 * @brief Asynchronously map a file in memory. 932 * @param f The file to map. 933 * @param rule The rule to apply to the map. 934 * @param filter_cb Callback called in the thread to validate the content of the map. 935 * @param map_cb Callback called in the main loop when the file has been successfully mapped. 936 * @param error_cb Callback called in the main loop when the file can't be mapped. 937 * @param data Unmodified user data passed to callbacks 938 * @return Pointer to the file if successful or NULL otherwise. 939 * 940 * The container of the Eio_File is the Eina_File. 941 */ 942 EAPI Eio_File *eio_file_map_all(Eina_File *f, 943 Eina_File_Populate rule, 944 Eio_Filter_Map_Cb filter_cb, 945 Eio_Map_Cb map_cb, 946 Eio_Error_Cb error_cb, 947 const void *data); 948 949 /** 950 * @brief Asynchronously map a part of a file in memory. 951 * @param f The file to map. 952 * @param rule The rule to apply to the map. 953 * @param offset The offset inside the file 954 * @param length The length of the memory to map 955 * @param filter_cb Callback called in the thread to validate the content of the map. 956 * @param map_cb Callback called in the main loop when the file has been successfully mapped. 957 * @param error_cb Callback called in the main loop when the file can't be mapped. 958 * @param data Unmodified user data passed to callbacks 959 * @return Pointer to the file if successful or NULL otherwise. 960 * 961 * The container of the Eio_File is the Eina_File. 962 */ 963 EAPI Eio_File *eio_file_map_new(Eina_File *f, 964 Eina_File_Populate rule, 965 unsigned long int offset, 966 unsigned long int length, 967 Eio_Filter_Map_Cb filter_cb, 968 Eio_Map_Cb map_cb, 969 Eio_Error_Cb error_cb, 970 const void *data); 971 972 /** 973 * @} 974 */ 975 976 /** 977 * @defgroup Eio_Eet Eio asynchronous API for Eet file. 978 * @ingroup Eio 979 * 980 * @brief This set of functions help in the asynchronous use of Eet 981 * 982 * @{ 983 */ 984 985 /** 986 * @brief Open an eet file on disk, and returns a handle to it asynchronously. 987 * @param filename The file path to the eet file. eg: @c "/tmp/file.eet". 988 * @param mode The mode for opening. Either EET_FILE_MODE_READ, 989 * EET_FILE_MODE_WRITE or EET_FILE_MODE_READ_WRITE. 990 * @param eet_cb The callback to call when the file has been successfully opened. 991 * @param error_cb Callback called in the main loop when the file can't be opened. 992 * @param data Unmodified user data passed to callbacks 993 * @return NULL in case of a failure. 994 * 995 * This function calls eet_open() from another thread using Ecore_Thread. 996 */ 997 EAPI Eio_File *eio_eet_open(const char *filename, 998 Eet_File_Mode mode, 999 Eio_Eet_Open_Cb eet_cb, 1000 Eio_Error_Cb error_cb, 1001 const void *data); 1002 /** 1003 * @brief Close an eet file handle and flush pending writes asynchronously. 1004 * @param ef A valid eet file handle. 1005 * @param done_cb Callback called from the main loop when the file has been closed. 1006 * @param error_cb Callback called in the main loop when the file can't be closed. 1007 * @param data Unmodified user data passed to callbacks 1008 * @return NULL in case of a failure. 1009 * 1010 * This function will call eet_close() from another thread by 1011 * using Ecore_Thread. You should assume that the Eet_File is dead after this 1012 * function is called. 1013 */ 1014 EAPI Eio_File *eio_eet_close(Eet_File *ef, 1015 Eio_Done_Cb done_cb, 1016 Eio_Eet_Error_Cb error_cb, 1017 const void *data); 1018 1019 /** 1020 * @brief Sync content of an eet file handle, flushing pending writes asynchronously. 1021 * @param ef A valid eet file handle. 1022 * @param done_cb Callback called from the main loop when the file has been synced. 1023 * @param error_cb Callback called in the main loop when the file can't be synced. 1024 * @param data Unmodified user data passed to callbacks 1025 * @return NULL in case of a failure. 1026 * 1027 * This function will call eet_sync() from another thread. As long as the done_cb or 1028 * error_cb haven't be called, you must keep @p ef open. 1029 */ 1030 EAPI Eio_File *eio_eet_sync(Eet_File *ef, 1031 Eio_Done_Cb done_cb, 1032 Eio_Eet_Error_Cb error_cb, 1033 const void *data); 1034 1035 /** 1036 * @brief Write a data structure from memory and store in an eet file 1037 * using a cipher asynchronously. 1038 * @param ef The eet file handle to write to. 1039 * @param edd The data descriptor to use when encoding. 1040 * @param name The key to store the data under in the eet file. 1041 * @param cipher_key The key to use as cipher. 1042 * @param write_data A pointer to the data structure to save and encode. 1043 * @param compress Compression flags for storage. 1044 * @param done_cb Callback called from the main loop when the data has been put in the Eet_File. 1045 * @param error_cb Callback called in the main loop when the file can't be written. 1046 * @param user_data Private data given to each callback. 1047 * @return NULL in case of a failure. 1048 */ 1049 EAPI Eio_File *eio_eet_data_write_cipher(Eet_File *ef, 1050 Eet_Data_Descriptor *edd, 1051 const char *name, 1052 const char *cipher_key, 1053 void *write_data, 1054 int compress, 1055 Eio_Done_Int_Cb done_cb, 1056 Eio_Error_Cb error_cb, 1057 const void *user_data); 1058 1059 /** 1060 * @brief Read a data structure from an eet file and decodes it using a cipher asynchronously. 1061 * @param ef The eet file handle to read from. 1062 * @param edd The data descriptor handle to use when decoding. 1063 * @param name The key the data is stored under in the eet file. 1064 * @param cipher_key The key to use as cipher. 1065 * @param done_cb Callback called from the main loop when the data has been read and decoded. 1066 * @param error_cb Callback called in the main loop when the data can't be read. 1067 * @param data Unmodified user data passed to callbacks 1068 * @return NULL in case of a failure. 1069 */ 1070 EAPI Eio_File *eio_eet_data_read_cipher(Eet_File *ef, 1071 Eet_Data_Descriptor *edd, 1072 const char *name, 1073 const char *cipher_key, 1074 Eio_Done_ERead_Cb done_cb, 1075 Eio_Error_Cb error_cb, 1076 const void *data); 1077 1078 /** 1079 * @brief Write image data to the named key in an eet file asynchronously. 1080 * @param ef A valid eet file handle opened for writing. 1081 * @param name Name of the entry. eg: "/base/file_i_want". 1082 * @param cipher_key The key to use as cipher. 1083 * @param write_data A pointer to the image pixel data. 1084 * @param w The width of the image in pixels. 1085 * @param h The height of the image in pixels. 1086 * @param alpha The alpha channel flag. 1087 * @param compress The compression amount. 1088 * @param quality The quality encoding amount. 1089 * @param lossy The lossiness flag. 1090 * @param done_cb Callback called from the main loop when the data has been put in the Eet_File. 1091 * @param error_cb Callback called in the main loop when the file can't be written. 1092 * @param user_data Private data given to each callback. 1093 * @return NULL in case of a failure. 1094 */ 1095 EAPI Eio_File *eio_eet_data_image_write_cipher(Eet_File *ef, 1096 const char *name, 1097 const char *cipher_key, 1098 void *write_data, 1099 unsigned int w, 1100 unsigned int h, 1101 int alpha, 1102 int compress, 1103 int quality, 1104 int lossy, 1105 Eio_Done_Int_Cb done_cb, 1106 Eio_Error_Cb error_cb, 1107 const void *user_data); 1108 1109 /** 1110 * @brief Read a specified entry from an eet file and return data 1111 * @param ef A valid eet file handle opened for reading. 1112 * @param name Name of the entry. eg: "/base/file_i_want". 1113 * @param done_cb Callback called from the main loop when the data has been read. 1114 * @param error_cb Callback called in the main loop when the data can't be read. 1115 * @param data Unmodified user data passed to callbacks 1116 * @return NULL in case of a failure. 1117 */ 1118 EAPI Eio_File *eio_eet_read_direct(Eet_File *ef, 1119 const char *name, 1120 Eio_Done_Data_Cb done_cb, 1121 Eio_Error_Cb error_cb, 1122 const void *data); 1123 1124 /** 1125 * @brief Read a specified entry from an eet file and return data 1126 * @param ef A valid eet file handle opened for reading. 1127 * @param name Name of the entry. eg: "/base/file_i_want". 1128 * @param cipher_key The key to use as cipher. 1129 * @param done_cb Callback called from the main loop when the data has been read. 1130 * @param error_cb Callback called in the main loop when the data can't be read. 1131 * @param data Unmodified user data passed to callbacks 1132 * @return NULL in case of a failure. 1133 */ 1134 EAPI Eio_File *eio_eet_read_cipher(Eet_File *ef, 1135 const char *name, 1136 const char *cipher_key, 1137 Eio_Done_Read_Cb done_cb, 1138 Eio_Error_Cb error_cb, 1139 const void *data); 1140 1141 /** 1142 * @brief Write a specified entry to an eet file handle using a cipher. 1143 * @param ef A valid eet file handle opened for writing. 1144 * @param name Name of the entry. eg: "/base/file_i_want". 1145 * @param write_data Pointer to the data to be stored. 1146 * @param size Length in bytes in the data to be stored. 1147 * @param compress Compression flags (1 == compress, 0 = don't compress). 1148 * @param cipher_key The key to use as cipher. 1149 * @param done_cb Callback called from the main loop when the data has been put in the Eet_File. 1150 * @param error_cb Callback called in the main loop when the file can't be written. 1151 * @param user_data Private data given to each callback. 1152 * @return NULL in case of a failure. 1153 */ 1154 EAPI Eio_File *eio_eet_write_cipher(Eet_File *ef, 1155 const char *name, 1156 void *write_data, 1157 int size, 1158 int compress, 1159 const char *cipher_key, 1160 Eio_Done_Int_Cb done_cb, 1161 Eio_Error_Cb error_cb, 1162 const void *user_data); 1163 1164 /** 1165 * @} 1166 */ 1167 1168 /** 1169 * @defgroup Eio_Monitor Eio file and directory monitoring API 1170 * @ingroup Eio 1171 * 1172 * @brief These function monitor changes in directories and files 1173 * 1174 * These functions use the best available method to monitor changes on a specified directory 1175 * or file. They send ecore events when changes occur, and they maintain internal refcounts to 1176 * reduce resource consumption on duplicate monitor targets. 1177 * 1178 * @{ 1179 */ 1180 1181 EAPI extern int EIO_MONITOR_FILE_CREATED; /**< A new file was created in a watched directory */ 1182 EAPI extern int EIO_MONITOR_FILE_DELETED; /**< A watched file was deleted, or a file in a watched directory was deleted */ 1183 EAPI extern int EIO_MONITOR_FILE_MODIFIED; /**< A file was modified in a watched directory */ 1184 EAPI extern int EIO_MONITOR_FILE_CLOSED; /**< A file was closed in a watched directory. This event is never sent on Windows and OSX, or for non-fallback monitors */ 1185 EAPI extern int EIO_MONITOR_DIRECTORY_CREATED; /**< A new directory was created in a watched directory */ 1186 EAPI extern int EIO_MONITOR_DIRECTORY_DELETED; /**< A directory has been deleted: this can be either a watched directory or one of its subdirectories */ 1187 EAPI extern int EIO_MONITOR_DIRECTORY_MODIFIED; /**< A directory has been modified in a watched directory */ 1188 EAPI extern int EIO_MONITOR_DIRECTORY_CLOSED; /**< A directory has been closed in a watched directory. This event is never sent on Windows and OSX, or for non-fallback monitors */ 1189 EAPI extern int EIO_MONITOR_SELF_RENAME; /**< The monitored path has been renamed, an error could happen just after if the renamed path doesn't exist. This event is never sent on OSX, or for non-fallback monitors */ 1190 EAPI extern int EIO_MONITOR_SELF_DELETED; /**< The monitored path has been removed. This event is never sent on OSX */ 1191 EAPI extern int EIO_MONITOR_ERROR; /**< During operation the monitor failed and will no longer work. eio_monitor_del must be called on it. */ 1192 1193 typedef struct _Eio_Monitor Eio_Monitor; 1194 1195 typedef struct _Eio_Monitor_Error Eio_Monitor_Error; 1196 typedef struct _Eio_Monitor_Event Eio_Monitor_Event; 1197 1198 struct _Eio_Monitor_Error 1199 { 1200 Eio_Monitor *monitor; 1201 int error; 1202 }; 1203 1204 struct _Eio_Monitor_Event 1205 { 1206 Eio_Monitor *monitor; 1207 const char *filename; 1208 }; 1209 1210 /** 1211 * @brief Adds a file/directory to monitor (inotify mechanism) 1212 * @param path file/directory to monitor 1213 * @return NULL in case of a failure or a pointer to the monitor in case of 1214 * success. 1215 * 1216 * This function will add the given path to its internal 1217 * list of files to monitor. It utilizes the inotify mechanism 1218 * introduced in kernel 2.6.13 for passive monitoring. 1219 */ 1220 EAPI Eio_Monitor *eio_monitor_add(const char *path); 1221 1222 /** 1223 * @brief Adds a file/directory to monitor 1224 * @param path file/directory to monitor 1225 * @return NULL in case of a failure or a pointer to the monitor in case of 1226 * success. 1227 * @warning Do NOT pass non-stringshared strings to this function! 1228 * If you don't know what this means, use eio_monitor_add(). 1229 * 1230 * This function is just like eio_monitor_add(), however the string passed by 1231 * argument must be created using eina_stringshare_add(). 1232 */ 1233 EAPI Eio_Monitor *eio_monitor_stringshared_add(const char *path); 1234 1235 /** 1236 * @brief Deletes a path from the “watched” list 1237 * @param monitor The Eio_Monitor you want to stop watching. 1238 * It can only be an Eio_Monitor returned to you from calling 1239 * eio_monitor_add() or eio_monitor_stringshared_add() 1240 */ 1241 EAPI void eio_monitor_del(Eio_Monitor *monitor); 1242 1243 /** 1244 * @brief returns the path being watched by the given 1245 * Eio_Monitor. 1246 * @param monitor Eio_Monitor to return the path of 1247 * @return The stringshared path belonging to @p monitor 1248 */ 1249 EAPI const char *eio_monitor_path_get(Eio_Monitor *monitor); 1250 1251 #ifdef EFL_BETA_API_SUPPORT 1252 /** 1253 * @brief Check whether a monitor is using the fallback backend 1254 * @param monitor The Eio_Monitor to check 1255 * @return EINA_TRUE only if the monitor is valid and is using the fallback monitoring mechanism 1256 * 1257 * Fallback monitors are unable to provide the CLOSED or RENAME events. It's important 1258 * to check whether a monitor is a fallback monitor before relying on these events. 1259 * 1260 * @since 1.21 1261 */ 1262 EAPI Eina_Bool eio_monitor_fallback_check(const Eio_Monitor *monitor); 1263 1264 /** 1265 * @brief Check if a monitor has the context about a file or not 1266 * @param monitor The Eio_Monitor to check 1267 * @param path The path to check 1268 * @return EINA_TRUE if there is context, EINA_FALSE otherwise. 1269 * 1270 * There are Monitors that need context about a file before they can monitor the file correctly. 1271 * As an example: If you publish a file in your API before the monitor has this file in his context, 1272 * and the file gets deleted as a reaction to this, the monitor will not be able to emit the correct DELETE 1273 * event even if the file is in the monitors path. 1274 * 1275 * In case the monitor does not yet have context, you can be sure that the monitor will bring up an FILE_ADD event about that file. 1276 * 1277 * @since 1.23 1278 */ 1279 EAPI Eina_Bool eio_monitor_has_context(const Eio_Monitor *monitor, const char *path); 1280 #endif 1281 /** 1282 * @} 1283 */ 1284 1285 #ifdef __cplusplus 1286 } 1287 #endif 1288