enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 1 Projects Releases Wiki Activity

[ecore-file] fix doc 

SVN revision: 53810
This commit is contained in:
Vincent Torri 2010-10-23 11:05:36 +00:00
parent 8055b915b7
commit 259b702319
6 changed files with 484 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
legacy/ecore/doc/ecore.dox.in
View File

@ -55,6 +55,7 @@ Ecore is a library of convenience functions.
The Ecore library provides the following modules:
@li @ref Ecore_Group
@li @ref Ecore_File_Group
@li @ref Ecore_Con_Group
@li @link Ecore_Evas.h Ecore_Evas - Evas convenience functions. @endlink
@li @ref Ecore_FB_Group

56
legacy/ecore/src/lib/ecore_file/Ecore_File.h
View File

@ -43,25 +43,53 @@
extern "C" {
#endif
/**
* @defgroup Ecore_File_Group Ecore_File - Files and direcotries convenience functions
*
* @{
*/
/**
* @typedef Ecore_File_Monitor
* Abstract type used when monitoring a directory.
*/
typedef struct _Ecore_File_Monitor Ecore_File_Monitor;
typedef struct _Ecore_File_Monitor_Event Ecore_File_Monitor_Event;
/**
* @typedef Ecore_File_Download_Job
* Abstract type used when aborting a download.
*/
typedef struct _Ecore_File_Download_Job Ecore_File_Download_Job;
typedef enum
/**
* @typedef Ecore_File_Event
* The event type returned when a file or directory is monitored.
*/
typedef enum _Ecore_File_Event Ecore_File_Event;
/**
* @enum _Ecore_File_Event
* The event type returned when a directory is monitored.
*/
enum _Ecore_File_Event
{
ECORE_FILE_EVENT_NONE,
ECORE_FILE_EVENT_CREATED_FILE,
ECORE_FILE_EVENT_CREATED_DIRECTORY,
ECORE_FILE_EVENT_DELETED_FILE,
ECORE_FILE_EVENT_DELETED_DIRECTORY,
ECORE_FILE_EVENT_DELETED_SELF,
ECORE_FILE_EVENT_MODIFIED
} Ecore_File_Event;
ECORE_FILE_EVENT_NONE, /**< No event. */
ECORE_FILE_EVENT_CREATED_FILE, /**< Created file event. */
ECORE_FILE_EVENT_CREATED_DIRECTORY, /**< Created directory event. */
ECORE_FILE_EVENT_DELETED_FILE, /**< Deleted file event. */
ECORE_FILE_EVENT_DELETED_DIRECTORY, /**< Deleted directory event. */
ECORE_FILE_EVENT_DELETED_SELF, /**< Deleted monitored directory event. */
ECORE_FILE_EVENT_MODIFIED /**< Modified file or directory event. */
};
/**
* @typedef Ecore_File_Monitor_Cb
* Callback type used when a monitored directory has changes.
*/
typedef void (*Ecore_File_Monitor_Cb)(void *data, Ecore_File_Monitor *em, Ecore_File_Event event, const char *path);
/* File operations */
typedef void (*Ecore_File_Monitor_Cb)(void *data, Ecore_File_Monitor *em, Ecore_File_Event event, const char *path);
EAPI int ecore_file_init (void);
EAPI int ecore_file_shutdown (void);
EAPI long long ecore_file_mod_time (const char *file);
@ -127,6 +155,10 @@ EAPI void ecore_file_download_abort_all(void);
EAPI void ecore_file_download_abort(Ecore_File_Download_Job *job);
EAPI Eina_Bool ecore_file_download_protocol_available(const char *protocol);
/**
* @}
*/
#ifdef __cplusplus
}
#endif

377
legacy/ecore/src/lib/ecore_file/ecore_file.c
View File

@ -26,11 +26,25 @@ int _ecore_file_log_dom = -1;
static int _ecore_file_init_count = 0;
/* externally accessible functions */
/**
* Initialize Ecore_File and the services it will use. Call this function
* once before you use any of the ecore file functions.
* @return Number of times ecore_file_init() was called successfully or 0 if
* this call failed.
* @addtogroup Ecore_File_Group Ecore_File - Files and direcotries convenience functions
*
* @{
*/
/**
* @brief Initialize the Ecore_File library.
*
* @return 1 or greater on success, 0 on error.
*
* This function sets up Ecore_File and the services it will use
* (monitoring, downloading, PATH related feature). It returns 0 on
* failure, otherwise it returns the number of times it has already
* been called.
*
* When Ecore_File is not used anymore, call ecore_file_shutdown()
* to shut down the Ecore_File library.
*/
EAPI int
ecore_file_init()
@ -71,8 +85,14 @@ ecore_file_init()
}
/**
* Shutdown the Ecore_File
* @return returns the number of libraries that still uses Ecore_File
* @brief Shut down the Ecore_File library.
*
* @return 0 when the library is completely shut down, 1 or
* greater otherwise.
*
* This function shuts down the Ecore_File library. It returns 0 when it has
* been called the same number of times than ecore_file_init(). In that case
* it shuts down all the services it uses.
*/
EAPI int
ecore_file_shutdown()
@ -89,10 +109,14 @@ ecore_file_shutdown()
}
/**
* Get the time of the last modification to the give file
* @param file The name of the file
* @return Return the time of the last data modification, if an error should
* occur it will return 0
* @brief Get the time of the last modification to the given file.
*
* @param file The name of the file.
* @return Return the time of the last data modification, or 0 on
* failure.
*
* This function returns the time of the last modification of
* @p file. On failure, it returns 0.
*/
EAPI long long
ecore_file_mod_time(const char *file)
@ -104,9 +128,13 @@ ecore_file_mod_time(const char *file)
}
/**
* Get the size of the given file
* @param file The name of the file
* @return The size of the file in byte
* @brief Get the size of the given file.
*
* @param file The name of the file.
* @return Return the size of the file in bytes, or 0 on failure.
*
* This function returns the size of @p file in bytes. On failure, it
* returns 0.
*/
EAPI long long
ecore_file_size(const char *file)
@ -118,9 +146,13 @@ ecore_file_size(const char *file)
}
/**
* Check if file exists
* @param file The name of the file
* @return EINA_TRUE if file exists on local filesystem, EINA_FALSE otherwise
* @brief Check if the given file exists.
*
* @param file The name of the file.
* @return Return EINA_TRUE if the file exists, EINA_FALSE otherwise.
*
* This function returns EINA_TRUE if @p file exists on local filesystem,
* EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_exists(const char *file)
@ -133,9 +165,14 @@ ecore_file_exists(const char *file)
}
/**
* Check if file is a directory
* @param file The name of the file
* @return EINA_TRUE if file exist and is a directory, EINA_FALSE otherwise
* @brief Check if the given file is a directory.
*
* @param file The name of the file.
* @return Return EINA_TRUE if the file exists and is a directory,
* EINA_FALSE otherwise.
*
* This function returns EINA_TRUE if @p file exists exists and is a
* directory on local filesystem, EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_is_dir(const char *file)
@ -150,11 +187,14 @@ ecore_file_is_dir(const char *file)
static mode_t default_mode = S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH;
/**
* Create a new directory
* @param dir The name of the directory to create
* @return EINA_TRUE on successful creation, EINA_FALSE on failure
* @brief Create a new directory.
*
* The directory is created with the mode: S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH
* @param dir The name of the directory to create
* @return EINA_TRUE on successful creation, EINA_FALSE otherwise.
*
* This function creates the directory @p dir with the mode S_IRUSR |
* S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH. On
* success, it returns EINA_TRUE, EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_mkdir(const char *dir)
@ -164,12 +204,17 @@ ecore_file_mkdir(const char *dir)
}
/**
* Create complete directory in a batch.
* @brief Create complete directory in a batch.
*
* @param dirs list of directories, null terminated.
* @return number of successful directories created, -1 if dirs is NULL.
* @param dirs The list of directories, null terminated.
* @return The number of successful directories created, -1 if dirs is
* @c NULL.
*
* @see ecore_file_mkdir() and ecore_file_mkpaths()
* This function creates all the directories that are in the null
* terminated array @p dirs. The function loops over the directories
* and call ecore_file_mkdir(). This function returns -1 if @p dirs is
* @c NULL, otherwise if returns the number of suceesfully created
* directories.
*/
EAPI int
ecore_file_mkdirs(const char **dirs)
@ -185,19 +230,22 @@ ecore_file_mkdirs(const char **dirs)
}
/**
* Create complete list of sub-directories in a batch (optimized).
* @brief Create complete list of sub-directories in a batch (optimized).
*
* @param base the base directory to act on, will be created if does
* not exists.
* @param subdirs list of directories, null terminated. These are
* created similarly to ecore_file_mkdir(), so same mode and whole
* path to that point must exists. So if creating base/a/b/c,
* provide subdirs with "a", "a/b" and "a/b/c" in that order!
* @param base The base directory to act on.
* @param subdirs The list of directories, null terminated.
* @return number of successful directories created, -1 on failure.
*
* @return number of successful directories created, -1 if subdirs or
* base is NULL or invalid.
*
* @see ecore_file_mkdir() and ecore_file_mkpaths()
* This function creates all the directories that are in the null
* terminated array @p dirs in the @p base directory. If @p base does
* not exist, it will be created. The function loops over the directories
* and call ecore_file_mkdir(). The whole path of the directories must
* exist. So if base/a/b/c wants to be created, @p subdirs must
* contain "a", "a/b" and "a/b/c", in that order. This function
* returns -1 if @p dirs or @p base are @c NULL, or if @p base is
* empty ("\0"). It returns 0 is @p base is not a directory or
* invalid, or if it can't be created. Otherwise if returns the number
* of suceesfully created directories.
*/
EAPI int
ecore_file_mksubdirs(const char *base, const char **subdirs)
@ -277,9 +325,13 @@ ecore_file_mksubdirs(const char *base, const char **subdirs)
}
/**
* Delete the given dir
* @param dir The name of the directory to delete
* @return EINA_TRUE on success, EINA_FALSE on failure
* @brief Delete the given directory.
*
* @param dir The name of the directory to delete.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function deletes @p dir. It returns EINA_TRUE on success,
* EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_rmdir(const char *dir)
@ -289,9 +341,13 @@ ecore_file_rmdir(const char *dir)
}
/**
* Delete the given file
* @param file The name of the file to delete
* @return EINA_TRUE on success, EINA_FALSE on failure
* @brief Delete the given file.
*
* @param file The name of the file to delete.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function deletes @p file. It returns EINA_TRUE on success,
* EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_unlink(const char *file)
@ -301,9 +357,13 @@ ecore_file_unlink(const char *file)
}
/**
* Remove the given file or directory
* @param file The name of the file or directory to delete
* @return EINA_TRUE on success, EINA_FALSE on failure
* @brief Remove the given file or directory.
*
* @param file The name of the file or directory to delete.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function removes @p file. It returns EINA_TRUE on success,
* EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_remove(const char *file)
@ -313,11 +373,14 @@ ecore_file_remove(const char *file)
}
/**
* Delete a directory and all its contents
* @param dir The name of the directory to delete
* @return EINA_TRUE on success, EINA_FALSE on failure
* @brief Delete the given directory and all its contents.
*
* If dir is a link only the link is removed
* @param dir The name of the directory to delete.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function delete @p dir and all its contents. If @p dir is a
* link only the link is removed. It returns EINA_TRUE on success,
* EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_recursive_rm(const char *dir)
@ -377,11 +440,15 @@ _ecore_file_mkpath_if_not_exists(const char *path)
}
/**
* Create a complete path
* @param path The path to create
* @return EINA_TRUE on success, EINA_FALSE on failure
* @brief Create a complete path.
*
* @see ecore_file_mkpaths() and ecore_file_mkdir()
* @param path The path to create
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function create @p path and all the subdirectories it
* contains. The separator is '/' so, on Windows, '\' must be replaced
* by '/'. If @p path exists, this function returns EINA_TRUE
* immediatly. It returns EINA_TRUE on success, EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_mkpath(const char *path)
@ -407,12 +474,17 @@ ecore_file_mkpath(const char *path)
}
/**
* Create complete paths in a batch.
* @brief Create complete paths in a batch.
*
* @param paths list of paths, null terminated.
* @return number of successful paths created, -1 if paths is NULL.
*
* @see ecore_file_mkpath() and ecore_file_mkdirs()
* This function creates all the directories that are in the null
* terminated array @p paths. The function loops over the directories
* and call ecore_file_mkpath(), hence on Windows, '\' must be
* replaced by '/' before calling that function. This function
* returns -1 if @p paths is @c NULL. Otherwise if returns the number
* of suceesfully created directories.
*/
EAPI int
ecore_file_mkpaths(const char **paths)
@ -428,10 +500,16 @@ ecore_file_mkpaths(const char **paths)
}
/**
* Copy a file
* @param src The name of the source file
* @param dst The name of the destination file
* @return EINA_TRUE on success, EINA_FALSE on failure
* @brief Copy the given file to the given destination.
*
* @param src The name of the source file.
* @param dst The name of the destination file.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function copies @p src to @p dst. If the absolute path name of
* @p src and @p dst can not be computed, or if they are equal, or if
* the copy fails, the function returns EINA_FALSE, otherwise it
* returns EINA_TRUE.
*/
EAPI Eina_Bool
ecore_file_cp(const char *src, const char *dst)
@ -463,10 +541,14 @@ ecore_file_cp(const char *src, const char *dst)
}
/**
* Move a file
* @param src The name of the source file
* @param dst The name of the destination file
* @return EINA_TRUE on success, EINA_FALSE on failure
* @brief Move the given file to the given destination.
*
* @param src The name of the source file.
* @param dst The name of the destination file.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function moves @p src to @p dst. It returns EINA_TRUE on
* success, EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_mv(const char *src, const char *dst)
@ -537,10 +619,15 @@ FAIL:
}
/**
* Create a symbolic link
* @param src The name of the file to link
* @param dest The name of link
* @return EINA_TRUE on success, EINA_FALSE on failure
* @brief Create a symbolic link.
*
* @param src The name of the file to link.
* @param dest The name of link.
* @return EINA_TRUE on success, EINA_FALSE otherwise.
*
* This function create the symbolic link @p dest of @p src. This
* function does not work on Windows. It returns EINA_TRUE on success,
* EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_symlink(const char *src, const char *dest)
@ -551,10 +638,16 @@ ecore_file_symlink(const char *src, const char *dest)
}
/**
* Get the canonicalized absolute pathname
* @param file The file path
* @return The canonicalized absolute pathname; on failure it will return
* an empty string
* @brief Get the canonicalized absolute path name.
*
* @param file The file path.
* @return The canonicalized absolute pathname or an empty string on
* failure.
*
* This function returns the absolute path name of @p file as a newly
* allocated string. If @p file is @c NULL, or on error, this function
* returns an empty string. Otherwise, it returns the absolute path
* name. When not needed anymore, the returned value must be freed.
*/
EAPI char *
ecore_file_realpath(const char *file)
@ -572,9 +665,13 @@ ecore_file_realpath(const char *file)
}
/**
* Get the filename from a give path
* @param path The complete path
* @return Only the file name
* Get the filename from a given path.
*
* @param path The complete path.
* @return The file name.
*
* This function returns the file name of @p path. If @p path is
* @c NULL, the functions returns @c NULL.
*/
EAPI const char *
ecore_file_file_get(const char *path)
@ -588,9 +685,15 @@ ecore_file_file_get(const char *path)
}
/**
* Get the directory where file reside
* @param file The name of the file
* @return The directory name
* @brief Get the directory where the given file resides.
*
* @param file The name of the file.
* @return The directory name.
*
* This function returns the directory where @p file resides as anewly
* allocated string. If @p file is @c NULL or on error, this function
* returns @c NULL. When not needed anymore, the returned value must
* be freed.
*/
EAPI char *
ecore_file_dir_get(const char *file)
@ -606,9 +709,13 @@ ecore_file_dir_get(const char *file)
}
/**
* Check if file can be read
* @param file The name of the file
* @return EINA_TRUE if the file is readable, EINA_FALSE otherwise
* @brief Check if the given file can be read.
*
* @param file The name of the file.
* @return EINA_TRUE if the file is readable, EINA_FALSE otherwise.
*
* This function returns EINA_TRUE if @p file can be read, EINA_FALSE
* otherwise.
*/
EAPI Eina_Bool
ecore_file_can_read(const char *file)
@ -619,9 +726,13 @@ ecore_file_can_read(const char *file)
}
/**
* Check if file can be written
* @param file The name of the file
* @return EINA_TRUE if the file is writable, EINA_FALSE otherwise
* @brief Check if the given file can be written.
*
* @param file The name of the file.
* @return EINA_TRUE if the file is writable, EINA_FALSE otherwise.
*
* This function returns EINA_TRUE if @p file can be written, EINA_FALSE
* otherwise.
*/
EAPI Eina_Bool
ecore_file_can_write(const char *file)
@ -632,9 +743,13 @@ ecore_file_can_write(const char *file)
}
/**
* Check if file can be executed
* @param file The name of the file
* @return EINA_TRUE if the file can be executed, EINA_FALSE otherwise
* @bbrief Check if the given file can be executed.
*
* @param file The name of the file.
* @return EINA_TRUE if the file can be executed, EINA_FALSE otherwise.
*
* This function returns EINA_TRUE if @p file can be executed, EINA_FALSE
* otherwise.
*/
EAPI Eina_Bool
ecore_file_can_exec(const char *file)
@ -645,9 +760,15 @@ ecore_file_can_exec(const char *file)
}
/**
* Get the path pointed by link
* @param link The name of the link
* @return The path pointed by link or NULL
* @brief Get the path pointed by the given link.
*
* @param link The name of the link.
* @return The path pointed by link or NULL.
*
* This function returns the path pointed by @p link as a newly
* allocated string. This function does not work on Windows. On
* failure, the function returns @c NULL. When not needed anymore, the
* returned value must be freed.
*/
EAPI char *
ecore_file_readlink(const char *link)
@ -661,14 +782,21 @@ ecore_file_readlink(const char *link)
}
/**
* Get the list of the files and directories in a given directory. The list
* will be sorted with strcoll as compare function. That means that you may
* want to set the current locale for the category LC_COLLATE with setlocale().
* For more information see the manual pages of strcoll and setlocale.
* The list will not contain the directory entries for '.' and '..'.
* @brief Get the list of the files and directories in the given
* directory.
*
* @param dir The name of the directory to list
* @return Return an Eina_List containing all the files in the directory;
* on failure it returns NULL.
*
* This function returns a list of allocated strings of all the files
* and directories contained in @p dir. The list will be sorted with
* strcoll as compare function. That means that you may want to set
* the current locale for the category LC_COLLATE with
* setlocale(). For more information see the manual pages of strcoll
* and setlocale. The list will not contain the directory entries for
* '.' and '..'. On failure, @c NULL is returned. When not needed
* anymore, the list elements must be freed.
*/
EAPI Eina_List *
ecore_file_ls(const char *dir)
@ -697,7 +825,14 @@ ecore_file_ls(const char *dir)
}
/**
* FIXME: To be documented.
* @brief Return the executable from the given command.
*
* @param app The application command, with parameters.
*
* This function returns the executable from @p app as a newly
* allocated string. Arguments are removed and escae characters are
* handled. If @p app is @c NULL, or on failure, the function returns
* @c NULL. When not needed anymore, the returned value must be freed.
*/
EAPI char *
ecore_file_app_exe_get(const char *app)
@ -792,7 +927,7 @@ restart:
in_quot_dbl = 0;
else
{
/* techcincally this is wrong. double quotes also accept
/* technically this is wrong. double quotes also accept
* special chars:
*
* $, `, \
@ -845,10 +980,16 @@ restart:
}
/**
* Add the escape sequence ('\\') to the given filename
* @param filename The file name
* @return The file name with special characters escaped; if the length of the
* resulting string is longer than PATH_MAX it will return NULL
* @brief Add the escape sequence ('\\') to the given file name.
*
* @param filename The file name.
* @return The file name with special characters escaped.
*
* This function adds the escape sequence ('\\') to the given file
* name and returns the result as a newly allocated string. If the
* length of the returned string is longer than PATH_MAX, or on
* failure, @c NULL is returned. When not needed anymore, the returned
* value must be freed.
*/
EAPI char *
ecore_file_escape_name(const char *filename)
@ -885,15 +1026,25 @@ ecore_file_escape_name(const char *filename)
}
/**
* Remove the extension from a given path
* @param path The name of the file
* @return A newly allocated string with the extension stripped out or NULL on errors
* @bried Remove the extension from the given file name.
*
* @param path The name of the file.
* @return A newly allocated string with the extension stripped out or
* NULL on errors.
*
* This function removes the extension from @p path and returns the
* result as a newly allocated string. If @p path is @c NULL, or on
* failure, the function returns @c NULL. When not needed anymore, the
* returned value must be freed.
*/
EAPI char *
ecore_file_strip_ext(const char *path)
{
char *p, *file = NULL;
if (!path)
return NULL;
p = strrchr(path, '.');
if (!p)
file = strdup(path);
@ -911,9 +1062,15 @@ ecore_file_strip_ext(const char *path)
}
/**
* Check if the given directory is empty. The '.' and '..' files will be ignored.
* @param dir The name of the directory to check
* @return 1 if directory is empty, 0 if it has at least one file or -1 in case of errors
* @brief Check if the given directory is empty.
*
* @param dir The name of the directory to check.
* @return 1 if directory is empty, 0 if it has at least one file or
* -1 in case of errors.
*
* This functions checks if @p dir is empty. The '.' and '..' files
* will be ignored. If @p dir is empty, 1 is returned, if it contains
* at least 1 file, 0 is returned. On failure, -1 is returned.
*/
EAPI int
ecore_file_dir_is_empty(const char *dir)
@ -936,3 +1093,7 @@ ecore_file_dir_is_empty(const char *dir)
closedir(dirp);
return 1;
}
/**
* @}
*/

112
legacy/ecore/src/lib/ecore_file/ecore_file_download.c
View File

@ -80,40 +80,47 @@ ecore_file_download_shutdown(void)
#endif /* BUILD_ECORE_CON */
}
EAPI void
ecore_file_download_abort_all(void)
{
#ifdef BUILD_ECORE_CON
Ecore_File_Download_Job *job;
EINA_LIST_FREE(_job_list, job)
ecore_file_download_abort(job);
#endif /* BUILD_ECORE_CON */
}
/**
* @addtogroup Ecore_File_Group Ecore_File - Files and direcotries convenience functions
*
* @{
*/
/**
* Download @p url to the given @p dst
* @param url The complete url to download
* @param dst The local file to save the downloaded to
* @param completion_cb A callback called on download complete
* @param progress_cb A callback called during the download operation
* @param data User data passed to both callbacks
* @param job_ret If the protocol in use is http or ftp, this parameter will be
* filled with the job. Then you can use ecore_file_download_abort() to cancel it.
*
* @brief Download the given url to the given destination.
*
* @param url The complete url to download.
* @param dst The local file to save the downloaded to.
* @param completion_cb A callback called on download complete.
* @param progress_cb A callback called during the download operation.
* @param data User data passed to both callbacks.
* @param job_ret Job used to abort the download.
* @return EINA_TRUE if the download start or EINA_FALSE on failure
*
* You must provide the full url, including 'http://', 'ftp://' or 'file://'.\n
* If @p dst already exist it will not be overwritten and the function will fail.\n
* Ecore must be compiled with CURL to download using http and ftp protocols.\n
* The @p status param in the @p completion_cb() will be 0 if the download goes well or
* 1 in case of failure.
* This function starts the download of the URL @p url and saves it to
* @p dst. @p url must provide the protocol, including 'http://',
* 'ftp://' or 'file://'. Ecore_File must be compiled with CURL to
* download using http and ftp protocols. If @p dst is ill-formed, or
* if it already exists, the function returns EINA_FALSE. When the
* download is complete, the callback @p completion_cb is called and
* @p data is passed to it. The @p status parameter of @p completion_cb
* will be filled with the status of the download (200, 404,...). The
* @p progress_cb is called during the download operation, each time a
* packet i received or when CURL wants. It can be used to display the
* percentage of the downloaded file. The only operations that can be
* aborted are those with protocol 'http' or 'ftp'. In that case @p job_ret
* can be filled. It can be used with ecore_file_download_abort() or
* ecore_file_download_abort_all() to respectively abort one or all
* download operations. This function returns EINA_TRUE if the
* download starts, EINA_FALSE otherwise.
*/
EAPI Eina_Bool
ecore_file_download(const char *url, const char *dst,
ecore_file_download(const char *url,
const char *dst,
void (*completion_cb)(void *data, const char *file, int status),
int (*progress_cb)(void *data, const char *file, long int dltotal, long int dlnow, long int ultotal, long int ulnow),
void *data, Ecore_File_Download_Job **job_ret)
void *data,
Ecore_File_Download_Job **job_ret)
{
#ifdef BUILD_ECORE_CON
char *dir = ecore_file_dir_get(dst);
@ -163,12 +170,15 @@ ecore_file_download(const char *url, const char *dst,
}
/**
* Check if the given protocol is available
* @param protocol The protocol to check
* @return EINA_TRUE if protocol is handled, EINA_FALSE otherwise
* @brief Check if the given protocol is available.
*
* @p protocol can be 'http://', 'ftp://' or 'file://'.\n
* Ecore must be compiled with CURL to handle http and ftp protocols.
* @param protocol The protocol to check.
* @return EINA_TRUE if protocol is handled, EINA_FALSE otherwise.
*
* This function returns EINA_TRUE if @p protocol is supported,
* EINA_FALSE otherwise. @p protocol can be 'http://', 'ftp://' or
* 'file://'. Ecore_FILE must be compiled with CURL to handle http and
* ftp protocols.
*/
EAPI Eina_Bool
ecore_file_download_protocol_available(const char *protocol)
@ -292,14 +302,23 @@ _ecore_file_download_curl(const char *url, const char *dst,
#endif
/**
* Abort the given download job and call the completion_cb function with a
* status of 1 (error)
* @param job The download job to abort
* @brief Abort the given download job and call the completion_cb
* callbck with a status of 1 (error).
*
* @param job The download job to abort.
*
* This function aborts a download operation started by
* ecore_file_download(). @p job is the #Ecore_File_Download_Job
* structure filled by ecore_file_download(). If it is @c NULL, this
* function does nothing. To abort all the currently downloading
* operations, call ecore_file_download_abort_all().
*/
EAPI void
ecore_file_download_abort(Ecore_File_Download_Job *job)
{
if (!job)
return;
#ifdef BUILD_ECORE_CON
if (job->completion_cb)
job->completion_cb(ecore_con_url_data_get(job->url_con), job->dst, 1);
@ -312,3 +331,26 @@ ecore_file_download_abort(Ecore_File_Download_Job *job)
free(job);
#endif /* BUILD_ECORE_CON */
}
/**
* @brief Abort all downloads.
*
* This function aborts all the downloads that have been started by
* ecore_file_download(). It loops over the started downloads and call
* ecore_file_download_abort() for each of them. To abort only one
* specific download operation, call ecore_file_download_abort().
*/
EAPI void
ecore_file_download_abort_all(void)
{
#ifdef BUILD_ECORE_CON
Ecore_File_Download_Job *job;
EINA_LIST_FREE(_job_list, job)
ecore_file_download_abort(job);
#endif /* BUILD_ECORE_CON */
}
/**
* @}
*/

70
legacy/ecore/src/lib/ecore_file/ecore_file_monitor.c
View File

@ -67,20 +67,36 @@ ecore_file_monitor_shutdown(void)
}
/**
* Monitor a path using inotify or polling
* @param path The path to monitor
* @param func The function to call on changes
* @param data The data passed to func
* @return An Ecore_File_Monitor pointer or NULL on failure
* @addtogroup Ecore_File_Group Ecore_File - Files and direcotries convenience functions
*
* @{
*/
/**
* @brief Monitor the given path using inotify, Windows notification, or polling.
*
* @param path The path to monitor.
* @param func The function to call on changes.
* @param data The data passed to func.
* @return An Ecore_File_Monitor pointer or NULL on failure.
*
* This function monitors @p path. If @p path is @c NULL, or is an
* empty string, or none of the notify methods (Inotify, Windows
* notification or polling) is available, or if @p path is not a file,
* the function returns @c NULL. Otherwise, it returns a newly
* allocated Ecore_File_Monitor object and the monitoring begins. When
* one of the #Ecore_File_Event event is notified, @p func is called
* and @p data is passed to @p func. Call ecore_file_monitor_del() to
* stop the monitoring.
*/
EAPI Ecore_File_Monitor *
ecore_file_monitor_add(const char *path,
void (*func) (void *data,
Ecore_File_Monitor *em,
Ecore_File_Event event,
const char *path),
void *data)
ecore_file_monitor_add(const char *path,
Ecore_File_Monitor_Cb func,
void *data)
{
if (!path || !*path)
return NULL;
switch (monitor_type)
{
case ECORE_FILE_MONITOR_TYPE_NONE:
@ -102,12 +118,22 @@ ecore_file_monitor_add(const char *path,
}
/**
* Stop monitoring a path
* @param em The Ecore_File_Monitor to stop
* @brief Stop the monitoring of the given path.
*
* @param em The Ecore_File_Monitor to stop.
*
* This function stops the the monitoring of the path that has been
* monitored by ecore_file_monitor_add(). @p em must be the value
* returned by ecore_file_monitor_add(). If @p em is @c NULL, or none
* of the notify methods (Inotify, Windows notification or polling) is
* availablethis function does nothing.
*/
EAPI void
ecore_file_monitor_del(Ecore_File_Monitor *em)
{
if (!em)
return;
switch (monitor_type)
{
case ECORE_FILE_MONITOR_TYPE_NONE:
@ -131,12 +157,24 @@ ecore_file_monitor_del(Ecore_File_Monitor *em)
}
/**
* Get the monitored path
* @param em The Ecore_File_Monitor to query
* @return The path that is monitored by @p em
* @brief Get the monitored path.
*
* @param em The Ecore_File_Monitor to query.
* @return The path that is monitored by @p em.
*
* This function returns the monitored path that has been
* monitored by ecore_file_monitor_add(). @p em must be the value
* returned by ecore_file_monitor_add(). If @p em is @c NULL, the
* function returns @c NULL.
*/
EAPI const char *
ecore_file_monitor_path_get(Ecore_File_Monitor *em)
{
if (!em)
return NULL;
return em->path;
}
/**
* @}
*/

47
legacy/ecore/src/lib/ecore_file/ecore_file_path.c
View File

@ -58,9 +58,21 @@ _ecore_file_path_from_env(const char *env)
}
/**
* Check if the given directory is in PATH
* @param The name of the directory to search in PATH
* @return EINA_TRUE if the directory exist in PATH, EINA_FALSE otherwise
* @addtogroup Ecore_File_Group Ecore_File - Files and direcotries convenience functions
*
* @{
*/
/**
* @brief Check if the given directory is in PATH.
*
* @param The name of the directory to search in PATH.
* @return EINA_TRUE if the directory exist in PATH, EINA_FALSE otherwise.
*
* This function checks if @p in_dir is in the environment variable
* PATH. If @p in_dir is @c NULL, or if PATH is empty, or @p in_dir is
* not in PATH, the function returns EINA_FALSE, otherwise it returns
* EINA_TRUE.
*/
EAPI Eina_Bool
ecore_file_path_dir_exists(const char *in_dir)
@ -68,6 +80,9 @@ ecore_file_path_dir_exists(const char *in_dir)
Eina_List *l;
char *dir;
if (!in_dir)
return EINA_FALSE;
if (!__ecore_file_path_bin) return EINA_FALSE;
EINA_LIST_FOREACH(__ecore_file_path_bin, l, dir)
{
@ -79,11 +94,16 @@ ecore_file_path_dir_exists(const char *in_dir)
}
/**
* Check if the given application is installed
* @brief Check if the given application is installed.
*
* @param exe The name of the application
* @return EINA_TRUE if the exe is in PATH and is executable, EINA_FALSE otherwise
* @return EINA_TRUE if the exe is in PATH and is executable,
* EINA_FALSE otherwise.
*
*
* This function check if the given name exist in PATH and is executable
* This function checks if @p exe exists in PATH and is executable. If
* @p exe is @c NULL or is not executable, the function returns
* EINA_FALSE, otherwise it returns EINA_TRUE.
*/
EAPI Eina_Bool
ecore_file_app_installed(const char *exe)
@ -106,8 +126,15 @@ ecore_file_app_installed(const char *exe)
}
/**
* Get a list of all the applications installed on the system
* @return An Eina_List containing all the executable files in the system
* @brief Get a list of all the applications installed on the system.
*
* @return An Eina_List containing all the executable files in the
* system.
*
* This function returns a list of allocated strings of all the
* executable files. If no files are found, the function returns
* @c NULL. When not needed anymore, the element of the list must be
* freed.
*/
EAPI Eina_List *
ecore_file_app_list(void)
@ -132,3 +159,7 @@ ecore_file_app_list(void)
return list;
}
/**
* @}
*/