diff --git a/src/lib/ecore_file/Ecore_File.h b/src/lib/ecore_file/Ecore_File.h index c78b0b1929..70c4af7b36 100644 --- a/src/lib/ecore_file/Ecore_File.h +++ b/src/lib/ecore_file/Ecore_File.h @@ -114,59 +114,535 @@ typedef int (*Ecore_File_Download_Progress_Cb)(void *data, /* File operations */ +/** + * @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 (void); + +/** + * @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 (void); + +/** + * @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); + +/** + * @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); + +/** + * @brief Check if the given file exists. + * + * @param file The name of the file. + * @return @c EINA_TRUE if the @p file exists, @c EINA_FALSE otherwise. + * + * This function returns @c EINA_TRUE if @p file exists on local filesystem, + * @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_exists (const char *file); + +/** + * @brief Check if the given file is a directory. + * + * @param file The name of the file. + * @return @c EINA_TRUE if the file exists and is a directory, @c EINA_FALSE + * otherwise. + * + * This function returns @c EINA_TRUE if @p file exists exists and is a + * directory on local filesystem, @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_is_dir (const char *file); + +/** + * @brief Create a new directory. + * + * @param dir The name of the directory to create + * @return @c EINA_TRUE on successful creation, @c 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 UNIX + * (mode is unsued on Windows). On success, it returns @c EINA_TRUE, + * @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_mkdir (const char *dir); + +/** + * @brief Create complete directory in a batch. + * + * @param dirs The list of directories, null terminated. + * @return The number of successful directories created, -1 if dirs is + * @c NULL. + * + * 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); + +/** + * @brief Create complete list of sub-directories in a batch (optimized). + * + * @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. + * + * This function creates all the directories that are in the null + * terminated array @p subdirs 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 subdirs 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); + +/** + * @brief Delete the given directory. + * + * @param dir The name of the directory to delete. + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. + * + * This function deletes @p dir. It returns @c EINA_TRUE on success, + * @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_rmdir (const char *dir); + +/** + * @brief Delete the given directory and all its contents. + * + * @param dir The name of the directory to delete. + * @return @c EINA_TRUE on success, @c 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 @c EINA_TRUE on success, + * @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_recursive_rm (const char *dir); + +/** + * @brief Create a complete path. + * + * @param path The path to create + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. + * + * This function creates @p path and all the subdirectories it + * contains. The separator is '/' or '\'. If @p path exists, this + * function returns @c EINA_TRUE immediately. It returns @c EINA_TRUE on + * success, @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_mkpath (const char *path); + +/** + * @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. + * + * 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); + +/** + * @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 @c EINA_TRUE on success, @c 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 @c EINA_FALSE, otherwise it + * returns @c EINA_TRUE. + */ EAPI Eina_Bool ecore_file_cp (const char *src, const char *dst); + +/** + * @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 @c EINA_TRUE on success, @c EINA_FALSE otherwise. + * + * This function moves @p src to @p dst. It returns @c EINA_TRUE on + * success, @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_mv (const char *src, const char *dst); + +/** + * @brief Create a symbolic link. + * + * @param src The name of the file to link. + * @param dest The name of link. + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. + * + * This function create the symbolic link @p dest of @p src. This + * function does not work on Windows. It returns @c EINA_TRUE on success, + * @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_symlink (const char *src, const char *dest); + +/** + * @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); + +/** + * @brief Delete the given file. + * + * @param file The name of the file to delete. + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. + * + * This function deletes @p file. It returns @c EINA_TRUE on success, + * @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_unlink (const char *file); + +/** + * @brief Remove the given file or directory. + * + * @param file The name of the file or directory to delete. + * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. + * + * This function removes @p file. It returns @c EINA_TRUE on success, + * @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_remove (const char *file); + +/** + * 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); + +/** + * @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 *path); + +/** + * @brief Check if the given file can be read. + * + * @param file The name of the file. + * @return @c EINA_TRUE if the @p file is readable, @c EINA_FALSE otherwise. + * + * This function returns @c EINA_TRUE if @p file can be read, @c EINA_FALSE + * otherwise. + */ EAPI Eina_Bool ecore_file_can_read (const char *file); + +/** + * @brief Check if the given file can be written. + * + * @param file The name of the file. + * @return @c EINA_TRUE if the @p file is writable, @c EINA_FALSE otherwise. + * + * This function returns @c EINA_TRUE if @p file can be written, @c EINA_FALSE + * otherwise. + */ EAPI Eina_Bool ecore_file_can_write (const char *file); + +/** + * @brief Check if the given file can be executed. + * + * @param file The name of the file. + * @return @c EINA_TRUE if the @p file can be executed, @c EINA_FALSE + * otherwise. + * + * This function returns @c EINA_TRUE if @p file can be executed, @c EINA_FALSE + * otherwise. + */ EAPI Eina_Bool ecore_file_can_exec (const char *file); + +/** + * @brief Get the path pointed by the given link. + * + * @param lnk 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); + +/** + * @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); + +/** + * @brief Return the executable from the given command. + * + * @param app The application command, with parameters. + * @return The executable from @p app as a newly allocated string. Arguments + * are removed and escape 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); + +/** + * @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); + +/** + * @brief 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 + * @c 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 *file); + +/** + * @brief Check if the given directory is empty. + * + * @param dir The name of the directory to check. + * @return @c 1 if directory is empty, @c 0 if it has at least one file or + * @c -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 one file, @c 0 is returned. On failure, @c -1 is returned. + */ EAPI int ecore_file_dir_is_empty (const char *dir); /* Monitoring */ +/** + * @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 does not exist + * 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, Ecore_File_Monitor_Cb func, void *data); + +/** + * @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 *ecore_file_monitor); + +/** + * @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 *ecore_file_monitor); /* Path */ +/** + * @brief Check if the given directory is in PATH. + * + * @param in_dir The name of the directory to search in PATH. + * @return @c EINA_TRUE if the directory exist in PATH, @c 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 @c EINA_FALSE, otherwise it returns + * @c EINA_TRUE. + */ EAPI Eina_Bool ecore_file_path_dir_exists(const char *in_dir); + +/** + * @brief Check if the given application is installed. + * + * @param exe The name of the application + * @return @c EINA_TRUE if the @p exe is in PATH and is executable, + * @c EINA_FALSE otherwise. + * + * 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 + * @c EINA_FALSE, otherwise it returns @c EINA_TRUE. + */ EAPI Eina_Bool ecore_file_app_installed(const char *exe); + +/** + * @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); /* Download */ +/** + * @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 @c EINA_TRUE if the download start or @c EINA_FALSE on 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 @c 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 is received or when CURL wants. It can be used to display the + * percentage of the downloaded file. Return 0 from this callback, if provided, + * to continue the operation or anything else to abort the download. The only + * operations that can be aborted are those with protocol 'http' or 'ftp'. In + * that case @p job_ret can be passed to ecore_file_download_abort() to abort + * that download job. Similarly ecore_file_download_abort_all() can be used to + * abort all download operations. This function returns @c EINA_TRUE if the + * download starts, @c EINA_FALSE otherwise. + */ EAPI Eina_Bool ecore_file_download(const char *url, const char *dst, Ecore_File_Download_Completion_Cb completion_cb, Ecore_File_Download_Progress_Cb progress_cb, void *data, Ecore_File_Download_Job **job_ret); + +/** + * @brief Download the given url to the given destination with additional headers. + * + * @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. + * @param headers pointer of header lists. + * @return @c EINA_TRUE if the download start or @c EINA_FALSE on failure. + */ EAPI Eina_Bool ecore_file_download_full(const char *url, const char *dst, Ecore_File_Download_Completion_Cb completion_cb, @@ -175,8 +651,41 @@ EAPI Eina_Bool ecore_file_download_full(const char *url, Ecore_File_Download_Job **job_ret, Eina_Hash *headers); +/** + * @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); + +/** + * @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); + +/** + * @brief Check if the given protocol is available. + * + * @param protocol The protocol to check. + * @return @c EINA_TRUE if protocol is handled, @c EINA_FALSE otherwise. + * + * This function returns @c EINA_TRUE if @p protocol is supported, + * @c 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); /** diff --git a/src/lib/ecore_file/ecore_file.c b/src/lib/ecore_file/ecore_file.c index 7a44680ba9..11c03c46d1 100644 --- a/src/lib/ecore_file/ecore_file.c +++ b/src/lib/ecore_file/ecore_file.c @@ -81,27 +81,6 @@ _ecore_file_stat(const char *file, return EINA_TRUE; } -/* externally accessible functions */ - -/** - * @addtogroup Ecore_File_Group Ecore_File - Files and directories 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() { @@ -144,16 +123,6 @@ ecore_file_init() */ } -/** - * @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() { @@ -172,16 +141,6 @@ ecore_file_shutdown() return _ecore_file_init_count; } -/** - * @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) { @@ -193,15 +152,6 @@ ecore_file_mod_time(const char *file) return time; } -/** - * @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) { @@ -213,15 +163,6 @@ ecore_file_size(const char *file) return size; } -/** - * @brief Check if the given file exists. - * - * @param file The name of the file. - * @return @c EINA_TRUE if the @p file exists, @c EINA_FALSE otherwise. - * - * This function returns @c EINA_TRUE if @p file exists on local filesystem, - * @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_exists(const char *file) { @@ -238,16 +179,6 @@ ecore_file_exists(const char *file) #endif } -/** - * @brief Check if the given file is a directory. - * - * @param file The name of the file. - * @return @c EINA_TRUE if the file exists and is a directory, @c EINA_FALSE - * otherwise. - * - * This function returns @c EINA_TRUE if @p file exists exists and is a - * directory on local filesystem, @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_is_dir(const char *file) { @@ -261,36 +192,12 @@ 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; -/** - * @brief Create a new directory. - * - * @param dir The name of the directory to create - * @return @c EINA_TRUE on successful creation, @c 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 UNIX - * (mode is unsued on Windows). On success, it returns @c EINA_TRUE, - * @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_mkdir(const char *dir) { return (mkdir(dir, default_mode) == 0); } -/** - * @brief Create complete directory in a batch. - * - * @param dirs The list of directories, null terminated. - * @return The number of successful directories created, -1 if dirs is - * @c NULL. - * - * 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) { @@ -304,24 +211,6 @@ ecore_file_mkdirs(const char **dirs) return i; } -/** - * @brief Create complete list of sub-directories in a batch (optimized). - * - * @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. - * - * This function creates all the directories that are in the null - * terminated array @p subdirs 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 subdirs 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) { @@ -404,15 +293,6 @@ ecore_file_mksubdirs(const char *base, const char **subdirs) return i; } -/** - * @brief Delete the given directory. - * - * @param dir The name of the directory to delete. - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. - * - * This function deletes @p dir. It returns @c EINA_TRUE on success, - * @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_rmdir(const char *dir) { @@ -420,15 +300,6 @@ ecore_file_rmdir(const char *dir) return EINA_TRUE; } -/** - * @brief Delete the given file. - * - * @param file The name of the file to delete. - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. - * - * This function deletes @p file. It returns @c EINA_TRUE on success, - * @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_unlink(const char *file) { @@ -436,15 +307,6 @@ ecore_file_unlink(const char *file) return EINA_TRUE; } -/** - * @brief Remove the given file or directory. - * - * @param file The name of the file or directory to delete. - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. - * - * This function removes @p file. It returns @c EINA_TRUE on success, - * @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_remove(const char *file) { @@ -452,16 +314,6 @@ ecore_file_remove(const char *file) return EINA_TRUE; } -/** - * @brief Delete the given directory and all its contents. - * - * @param dir The name of the directory to delete. - * @return @c EINA_TRUE on success, @c 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 @c EINA_TRUE on success, - * @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_recursive_rm(const char *dir) { @@ -532,17 +384,6 @@ _ecore_file_mkpath_if_not_exists(const char *path) return EINA_TRUE; } -/** - * @brief Create a complete path. - * - * @param path The path to create - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. - * - * This function creates @p path and all the subdirectories it - * contains. The separator is '/' or '\'. If @p path exists, this - * function returns @c EINA_TRUE immediately. It returns @c EINA_TRUE on - * success, @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_mkpath(const char *path) { @@ -568,19 +409,6 @@ ecore_file_mkpath(const char *path) return _ecore_file_mkpath_if_not_exists(ss); } -/** - * @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. - * - * 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) { @@ -594,18 +422,6 @@ ecore_file_mkpaths(const char **paths) return i; } -/** - * @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 @c EINA_TRUE on success, @c 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 @c EINA_FALSE, otherwise it - * returns @c EINA_TRUE. - */ EAPI Eina_Bool ecore_file_cp(const char *src, const char *dst) { @@ -635,16 +451,6 @@ ecore_file_cp(const char *src, const char *dst) return ret; } -/** - * @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 @c EINA_TRUE on success, @c EINA_FALSE otherwise. - * - * This function moves @p src to @p dst. It returns @c EINA_TRUE on - * success, @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_mv(const char *src, const char *dst) { @@ -711,17 +517,6 @@ FAIL: return EINA_FALSE; } -/** - * @brief Create a symbolic link. - * - * @param src The name of the file to link. - * @param dest The name of link. - * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise. - * - * This function create the symbolic link @p dest of @p src. This - * function does not work on Windows. It returns @c EINA_TRUE on success, - * @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_symlink(const char *src, const char *dest) { @@ -730,18 +525,6 @@ ecore_file_symlink(const char *src, const char *dest) return EINA_FALSE; } -/** - * @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) { @@ -757,15 +540,6 @@ ecore_file_realpath(const char *file) return strdup(buf); } -/** - * 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) { @@ -791,17 +565,6 @@ ecore_file_file_get(const char *path) return result; } -/** - * @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) { @@ -815,15 +578,6 @@ ecore_file_dir_get(const char *file) return strdup(p); } -/** - * @brief Check if the given file can be read. - * - * @param file The name of the file. - * @return @c EINA_TRUE if the @p file is readable, @c EINA_FALSE otherwise. - * - * This function returns @c EINA_TRUE if @p file can be read, @c EINA_FALSE - * otherwise. - */ EAPI Eina_Bool ecore_file_can_read(const char *file) { @@ -832,15 +586,6 @@ ecore_file_can_read(const char *file) return EINA_FALSE; } -/** - * @brief Check if the given file can be written. - * - * @param file The name of the file. - * @return @c EINA_TRUE if the @p file is writable, @c EINA_FALSE otherwise. - * - * This function returns @c EINA_TRUE if @p file can be written, @c EINA_FALSE - * otherwise. - */ EAPI Eina_Bool ecore_file_can_write(const char *file) { @@ -849,16 +594,6 @@ ecore_file_can_write(const char *file) return EINA_FALSE; } -/** - * @brief Check if the given file can be executed. - * - * @param file The name of the file. - * @return @c EINA_TRUE if the @p file can be executed, @c EINA_FALSE - * otherwise. - * - * This function returns @c EINA_TRUE if @p file can be executed, @c EINA_FALSE - * otherwise. - */ EAPI Eina_Bool ecore_file_can_exec(const char *file) { @@ -867,17 +602,6 @@ ecore_file_can_exec(const char *file) return EINA_FALSE; } -/** - * @brief Get the path pointed by the given link. - * - * @param lnk 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 *lnk) { @@ -889,23 +613,6 @@ ecore_file_readlink(const char *lnk) return strdup(buf); } -/** - * @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) { @@ -930,15 +637,6 @@ ecore_file_ls(const char *dir) return list; } -/** - * @brief Return the executable from the given command. - * - * @param app The application command, with parameters. - * @return The executable from @p app as a newly allocated string. Arguments - * are removed and escape 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) { @@ -1001,18 +699,6 @@ ecore_file_app_exe_get(const char *app) return exe; } -/** - * @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) { @@ -1071,18 +757,6 @@ ecore_file_escape_name(const char *filename) return strdup(buf); } -/** - * @brief 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 - * @c 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) { @@ -1107,17 +781,6 @@ ecore_file_strip_ext(const char *path) return file; } -/** - * @brief Check if the given directory is empty. - * - * @param dir The name of the directory to check. - * @return @c 1 if directory is empty, @c 0 if it has at least one file or - * @c -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 one file, @c 0 is returned. On failure, @c -1 is returned. - */ EAPI int ecore_file_dir_is_empty(const char *dir) { @@ -1136,7 +799,3 @@ ecore_file_dir_is_empty(const char *dir) eina_iterator_free(it); return 1; } - -/** - * @} - */ diff --git a/src/lib/ecore_file/ecore_file_download.c b/src/lib/ecore_file/ecore_file_download.c index 83c5884315..e9c047f7c1 100644 --- a/src/lib/ecore_file/ecore_file_download.c +++ b/src/lib/ecore_file/ecore_file_download.c @@ -147,41 +147,6 @@ _ecore_file_download(const char *url, } } -/** - * @addtogroup Ecore_File_Group Ecore_File - Files and directories convenience functions - * - * @{ - */ - -/** - * @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 @c EINA_TRUE if the download start or @c EINA_FALSE on 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 @c 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 is received or when CURL wants. It can be used to display the - * percentage of the downloaded file. Return 0 from this callback, if provided, - * to continue the operation or anything else to abort the download. The only - * operations that can be aborted are those with protocol 'http' or 'ftp'. In - * that case @p job_ret can be passed to ecore_file_download_abort() to abort - * that download job. Similarly ecore_file_download_abort_all() can be used to - * abort all download operations. This function returns @c EINA_TRUE if the - * download starts, @c EINA_FALSE otherwise. - */ EAPI Eina_Bool ecore_file_download(const char *url, const char *dst, @@ -193,18 +158,6 @@ ecore_file_download(const char *url, return _ecore_file_download(url, dst, completion_cb, progress_cb, data, job_ret, NULL); } -/** - * @brief Download the given url to the given destination with additional headers. - * - * @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. - * @param headers pointer of header lists. - * @return @c EINA_TRUE if the download start or @c EINA_FALSE on failure. - */ EAPI Eina_Bool ecore_file_download_full(const char *url, const char *dst, @@ -217,17 +170,6 @@ ecore_file_download_full(const char *url, return _ecore_file_download(url, dst, completion_cb, progress_cb, data, job_ret, headers); } -/** - * @brief Check if the given protocol is available. - * - * @param protocol The protocol to check. - * @return @c EINA_TRUE if protocol is handled, @c EINA_FALSE otherwise. - * - * This function returns @c EINA_TRUE if @p protocol is supported, - * @c 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) { @@ -348,18 +290,6 @@ _ecore_file_download_curl(const char *url, const char *dst, return job; } -/** - * @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) { @@ -375,14 +305,6 @@ ecore_file_download_abort(Ecore_File_Download_Job *job) free(job); } -/** - * @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) { @@ -391,7 +313,3 @@ ecore_file_download_abort_all(void) EINA_LIST_FREE(_job_list, job) ecore_file_download_abort(job); } - -/** - * @} - */ diff --git a/src/lib/ecore_file/ecore_file_monitor.c b/src/lib/ecore_file/ecore_file_monitor.c index 7b4f625534..3fb839b2eb 100644 --- a/src/lib/ecore_file/ecore_file_monitor.c +++ b/src/lib/ecore_file/ecore_file_monitor.c @@ -18,29 +18,6 @@ ecore_file_monitor_shutdown(void) ecore_file_monitor_backend_shutdown(); } -/** - * @addtogroup Ecore_File_Group Ecore_File - Files and directories 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 does not exist - * 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, Ecore_File_Monitor_Cb func, @@ -53,17 +30,6 @@ ecore_file_monitor_add(const char *path, return ecore_file_monitor_backend_add(path, func, data); } -/** - * @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) { @@ -72,24 +38,9 @@ ecore_file_monitor_del(Ecore_File_Monitor *em) ecore_file_monitor_backend_del(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) { EINA_SAFETY_ON_NULL_RETURN_VAL(em, NULL); return em->path; } - -/** - * @} - */ diff --git a/src/lib/ecore_file/ecore_file_path.c b/src/lib/ecore_file/ecore_file_path.c index 71fdb680ec..0c4e466ce5 100644 --- a/src/lib/ecore_file/ecore_file_path.c +++ b/src/lib/ecore_file/ecore_file_path.c @@ -68,23 +68,6 @@ _ecore_file_path_from_env(const char *env) return path; } -/** - * @addtogroup Ecore_File_Group Ecore_File - Files and directories convenience functions - * - * @{ - */ - -/** - * @brief Check if the given directory is in PATH. - * - * @param in_dir The name of the directory to search in PATH. - * @return @c EINA_TRUE if the directory exist in PATH, @c 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 @c EINA_FALSE, otherwise it returns - * @c EINA_TRUE. - */ EAPI Eina_Bool ecore_file_path_dir_exists(const char *in_dir) { @@ -104,17 +87,6 @@ ecore_file_path_dir_exists(const char *in_dir) return EINA_FALSE; } -/** - * @brief Check if the given application is installed. - * - * @param exe The name of the application - * @return @c EINA_TRUE if the @p exe is in PATH and is executable, - * @c EINA_FALSE otherwise. - * - * 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 - * @c EINA_FALSE, otherwise it returns @c EINA_TRUE. - */ EAPI Eina_Bool ecore_file_app_installed(const char *exe) { @@ -135,17 +107,6 @@ ecore_file_app_installed(const char *exe) return EINA_FALSE; } -/** - * @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) { @@ -169,7 +130,3 @@ ecore_file_app_list(void) return list; } - -/** - * @} - */ diff --git a/src/lib/ecore_ipc/Ecore_Ipc.h b/src/lib/ecore_ipc/Ecore_Ipc.h index 301ea24c43..928ade94c7 100644 --- a/src/lib/ecore_ipc/Ecore_Ipc.h +++ b/src/lib/ecore_ipc/Ecore_Ipc.h @@ -33,6 +33,7 @@ * @defgroup Ecore_IPC_Group Ecore_IPC - Ecore inter-process communication functions. * @ingroup Ecore * + * Functions that set up and shut down the Ecore IPC Library. * * @{ */ @@ -325,37 +326,287 @@ EAPI extern int ECORE_IPC_EVENT_SERVER_DEL; EAPI extern int ECORE_IPC_EVENT_CLIENT_DATA; EAPI extern int ECORE_IPC_EVENT_SERVER_DATA; +/** + * @brief Initialises the Ecore IPC library. + * @return Number of times the library has been initialised without + * being shut down. + * @ingroup Ecore_IPC_Group + */ EAPI int ecore_ipc_init(void); + +/** + * @brief Shuts down the Ecore IPC library. + * @return Number of times the library has been initialised without being + * shut down. + * @ingroup Ecore_IPC_Group + */ EAPI int ecore_ipc_shutdown(void); -/* FIXME: need to add protocol type parameter */ +/** + * @defgroup Ecore_IPC_Server_Group IPC Server Functions + * @ingroup Ecore_IPC_Group + * + * Functions the deal with IPC server objects. + */ + +/** + * @brief Creates an IPC server that listens for connections. + * + * For more details about the @p compl_type, @p name and @p port + * parameters, see the @ref ecore_con_server_add documentation. + * + * @param compl_type The connection type. + * @param name Name to associate with the socket used for connection. + * @param port Number to identify with socket used for connection. + * @param data Data to associate with the IPC server. + * @return New IPC server. If there is an error, @c NULL is returned. + * @ingroup Ecore_IPC_Server_Group + * @todo Need to add protocol type parameter to this function. + */ EAPI Ecore_Ipc_Server *ecore_ipc_server_add(Ecore_Ipc_Type type, const char *name, int port, const void *data); -/* FIXME: need to add protocol type parameter */ +/** + * @brief Creates an IPC server object to represent the IPC server listening + * on the given port. + * + * For more details about the @p compl_type, @p name and @p port + * parameters, see the @ref ecore_con_server_connect documentation. + * + * @param compl_type The IPC connection type. + * @param name Name used to determine which socket to use for the + * IPC connection. + * @param port Number used to identify the socket to use for the + * IPC connection. + * @param data Data to associate with the server. + * @return A new IPC server. @c NULL is returned on error. + * @ingroup Ecore_IPC_Server_Group + * @todo Need to add protocol type parameter. + */ EAPI Ecore_Ipc_Server *ecore_ipc_server_connect(Ecore_Ipc_Type type, char *name, int port, const void *data); + +/** + * @brief Closes the connection and frees the given IPC server. + * @param svr The given IPC server. + * @return The data associated with the server when it was created. + * @ingroup Ecore_IPC_Server_Group + */ EAPI void *ecore_ipc_server_del(Ecore_Ipc_Server *svr); + +/** + * @brief Retrieves the data associated with the given IPC server. + * @param svr The given IPC server. + * @return The associated data. + * @ingroup Ecore_IPC_Server_Group + */ EAPI void *ecore_ipc_server_data_get(Ecore_Ipc_Server *svr); + +/** + * @brief Retrieves whether the given IPC server is currently connected. + * @param svr The given IPC server. + * @return @c EINA_TRUE if the server is connected, @c EINA_FALSE otherwise. + * @ingroup Ecore_IPC_Server_Group + */ EAPI Eina_Bool ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr); + +/** + * @brief Retrieves the list of clients for this server. + * @param svr The given IPC server. + * @return An Eina_List with the clients. + * @ingroup Ecore_IPC_Server_Group + */ EAPI Eina_List *ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr); -/* FIXME: this needs to become an ipc message */ + +/** + * @brief Sends a message to the given IPC server. + * + * The content of the parameters, excluding the @p svr parameter, is up to + * the client. + * + * @param svr The given IPC server. + * @param major Major opcode of the message. + * @param minor Minor opcode of the message. + * @param ref Message reference number. + * @param ref_to Reference number of the message this message refers to. + * @param response Requires response. + * @param data The data to send as part of the message. + * @param size Length of the data, in bytes, to send. + * @return Number of bytes sent. @c 0 is returned if there is an error. + * @ingroup Ecore_IPC_Server_Group + * @todo This function needs to become an IPC message. + * @todo Fix up the documentation: Make sure what ref_to and response are. + */ EAPI int ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int ref_to, int response, const void *data, int size); + +/** + * @brief Sets a limit on the number of clients that can be handled concurrently + * by the given server, and a policy on what to do if excess clients try to + * connect. + * Beware that if you set this once ecore is already running, you may + * already have pending CLIENT_ADD events in your event queue. Those + * clients have already connected and will not be affected by this call. + * Only clients subsequently trying to connect will be affected. + * @param svr The given server. + * @param client_limit The maximum number of clients to handle + * concurrently. -1 means unlimited (default). 0 + * effectively disables the server. + * @param reject_excess_clients Set to 1 to automatically disconnect + * excess clients as soon as they connect if you are + * already handling client_limit clients. Set to 0 + * (default) to just hold off on the "accept()" + * system call until the number of active clients + * drops. This causes the kernel to queue up to 4096 + * connections (or your kernel's limit, whichever is + * lower). + * @ingroup Ecore_Ipc_Server_Group + */ EAPI void ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char reject_excess_clients); + +/** + * @brief Sets the max data payload size for an Ipc message in bytes + * + * @param svr The given server. + * @param size The maximum data payload size in bytes. + * @ingroup Ecore_Ipc_Server_Group + */ EAPI void ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *srv, int size); + +/** + * @brief Gets the max data payload size for an Ipc message in bytes + * + * @param svr The given server. + * @return The maximum data payload in bytes. + * @ingroup Ecore_Ipc_Server_Group + */ EAPI int ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *srv); + +/** + * @brief Gets the IP address of a server that has been connected to. + * + * @param svr The given server. + * @return A pointer to an internal string that contains the IP address of + * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation. + * This string should not be modified or trusted to stay valid after + * deletion for the @p svr object. If no IP is known NULL is returned. + * @ingroup Ecore_Ipc_Server_Group + */ EAPI const char *ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr); + +/** + * @brief Flushes all pending data to the given server. Will return when done. + * + * @param svr The given server. + * @ingroup Ecore_Ipc_Server_Group + */ EAPI void ecore_ipc_server_flush(Ecore_Ipc_Server *svr); - -/* FIXME: this needs to become an ipc message */ + +/** + * @defgroup Ecore_IPC_Client_Group IPC Client Functions + * @ingroup Ecore_IPC_Group + * + * Functions that deal with IPC client objects. + */ + +/** + * @brief Sends a message to the given IPC client. + * + * @param cl The given IPC client. + * @param major Major opcode of the message. + * @param minor Minor opcode of the message. + * @param ref Reference number of the message. + * @param ref_to Reference number of the message this message refers to. + * @param response Requires response. + * @param data The data to send as part of the message. + * @param size Length of the data, in bytes, to send. + * @return The number of bytes sent. @c 0 will be returned if there is + * an error. + * @ingroup Ecore_IPC_Client_Group + * @todo This function needs to become an IPC message. + * @todo Make sure ref_to and response parameters are described correctly. + */ EAPI int ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int ref_to, int response, const void *data, int size); + +/** + * @brief Retrieves the IPC server that the given IPC client is connected to. + * + * @param cl The given IPC client. + * @return The IPC server the IPC client is connected to. + * @ingroup Ecore_IPC_Client_Group + */ EAPI Ecore_Ipc_Server *ecore_ipc_client_server_get(Ecore_Ipc_Client *cl); + +/** + * @brief Closes the connection and frees memory allocated to the given IPC + * client. + * + * @param cl The given client. + * @return Data associated with the client. + * @ingroup Ecore_IPC_Client_Group + */ EAPI void *ecore_ipc_client_del(Ecore_Ipc_Client *cl); + +/** + * @brief Sets the IPC data associated with the given IPC client to @p data. + * + * @param cl The given IPC client. + * @param data The data to associate with the IPC client. + * @ingroup Ecore_IPC_Client_Group + */ EAPI void ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data); + +/** + * @brief Retrieves the data that has been associated with the given IPC client. + * + * @param cl The given client. + * @return The data associated with the IPC client. + * @ingroup Ecore_IPC_Client_Group + */ EAPI void *ecore_ipc_client_data_get(Ecore_Ipc_Client *cl); + +/** + * @brief Sets the max data payload size for an Ipc message in bytes + * + * @param cl The given client. + * @param size The maximum data payload size in bytes. + * @ingroup Ecore_Ipc_Client_Group + */ EAPI void ecore_ipc_client_data_size_max_set(Ecore_Ipc_Client *cl, int size); + +/** + * @brief Gets the max data payload size for an Ipc message in bytes + * + * @param cl The given client. + * @return The maximum data payload size in bytes on success, @c -1 on failure. + * @ingroup Ecore_Ipc_Client_Group + */ EAPI int ecore_ipc_client_data_size_max_get(Ecore_Ipc_Client *cl); + +/** + * @brief Gets the IP address of a client that has been connected to. + * + * @param cl The given client. + * @return A pointer to an internal string that contains the IP address of + * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation. + * This string should not be modified or trusted to stay valid after + * deletion for the @p cl object. If no IP is known @c NULL is + * returned. + * @ingroup Ecore_Ipc_Client_Group + */ EAPI const char *ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl); + +/** + * @brief Flushes all pending data to the given client. Will return when done. + * + * @param cl The given client. + * @ingroup Ecore_Ipc_Client_Group + */ EAPI void ecore_ipc_client_flush(Ecore_Ipc_Client *cl); +/** + * @brief Returns if SSL support is available + * + * @return 1 if SSL is available, 0 if it is not. + * @ingroup Ecore_Con_Client_Group + */ EAPI int ecore_ipc_ssl_available_get(void); /* FIXME: need to add a callback to "ok" large ipc messages greater than */ /* a certain size (security/DOS attack safety) */ diff --git a/src/lib/ecore_ipc/ecore_ipc.c b/src/lib/ecore_ipc/ecore_ipc.c index 219c9503b6..0e6c2865d0 100644 --- a/src/lib/ecore_ipc/ecore_ipc.c +++ b/src/lib/ecore_ipc/ecore_ipc.c @@ -231,19 +231,6 @@ static int _ecore_ipc_init_count = 0; static Eina_List *servers = NULL; static Ecore_Event_Handler *handler[6]; -/** - * @defgroup Ecore_IPC_Library_Group Ecore_IPC - Inter Process Communication Library Functions - * @ingroup Ecore - * - * Functions that set up and shut down the Ecore IPC Library. - */ - -/** - * Initialises the Ecore IPC library. - * @return Number of times the library has been initialised without - * being shut down. - * @ingroup Ecore_IPC_Library_Group - */ EAPI int ecore_ipc_init(void) { @@ -283,12 +270,6 @@ ecore_ipc_init(void) return _ecore_ipc_init_count; } -/** - * Shuts down the Ecore IPC library. - * @return Number of times the library has been initialised without being - * shut down. - * @ingroup Ecore_IPC_Library_Group - */ EAPI int ecore_ipc_shutdown(void) { @@ -311,27 +292,7 @@ ecore_ipc_shutdown(void) return _ecore_ipc_init_count; } -/** - * @defgroup Ecore_IPC_Server_Group IPC Server Functions - * @ingroup Ecore_IPC_Library_Group - * - * Functions the deal with IPC server objects. - */ - -/** - * Creates an IPC server that listens for connections. - * - * For more details about the @p compl_type, @p name and @p port - * parameters, see the @ref ecore_con_server_add documentation. - * - * @param compl_type The connection type. - * @param name Name to associate with the socket used for connection. - * @param port Number to identify with socket used for connection. - * @param data Data to associate with the IPC server. - * @return New IPC server. If there is an error, @c NULL is returned. - * @ingroup Ecore_IPC_Server_Group - * @todo Need to add protocol type parameter to this function. - */ +/* FIXME: need to add protocol type parameter */ EAPI Ecore_Ipc_Server * ecore_ipc_server_add(Ecore_Ipc_Type compl_type, const char *name, int port, const void *data) { @@ -373,23 +334,7 @@ ecore_ipc_server_add(Ecore_Ipc_Type compl_type, const char *name, int port, cons return svr; } -/** - * Creates an IPC server object to represent the IPC server listening - * on the given port. - * - * For more details about the @p compl_type, @p name and @p port - * parameters, see the @ref ecore_con_server_connect documentation. - * - * @param compl_type The IPC connection type. - * @param name Name used to determine which socket to use for the - * IPC connection. - * @param port Number used to identify the socket to use for the - * IPC connection. - * @param data Data to associate with the server. - * @return A new IPC server. @c NULL is returned on error. - * @ingroup Ecore_IPC_Server_Group - * @todo Need to add protocol type parameter. - */ +/* FIXME: need to add protocol type parameter */ EAPI Ecore_Ipc_Server * ecore_ipc_server_connect(Ecore_Ipc_Type compl_type, char *name, int port, const void *data) { @@ -433,12 +378,6 @@ ecore_ipc_server_connect(Ecore_Ipc_Type compl_type, char *name, int port, const return svr; } -/** - * Closes the connection and frees the given IPC server. - * @param svr The given IPC server. - * @return The data associated with the server when it was created. - * @ingroup Ecore_IPC_Server_Group - */ EAPI void * ecore_ipc_server_del(Ecore_Ipc_Server *svr) { @@ -475,12 +414,6 @@ ecore_ipc_server_del(Ecore_Ipc_Server *svr) return data; } -/** - * Retrieves the data associated with the given IPC server. - * @param svr The given IPC server. - * @return The associated data. - * @ingroup Ecore_IPC_Server_Group - */ EAPI void * ecore_ipc_server_data_get(Ecore_Ipc_Server *svr) { @@ -493,12 +426,6 @@ ecore_ipc_server_data_get(Ecore_Ipc_Server *svr) return svr->data; } -/** - * Retrieves whether the given IPC server is currently connected. - * @param svr The given IPC server. - * @return @c EINA_TRUE if the server is connected, @c EINA_FALSE otherwise. - * @ingroup Ecore_IPC_Server_Group - */ EAPI Eina_Bool ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr) { @@ -511,12 +438,6 @@ ecore_ipc_server_connected_get(Ecore_Ipc_Server *svr) return ecore_con_server_connected_get(svr->server); } -/** - * Retrieves the list of clients for this server. - * @param svr The given IPC server. - * @return An Eina_List with the clients. - * @ingroup Ecore_IPC_Server_Group - */ EAPI Eina_List * ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr) { @@ -561,25 +482,7 @@ ecore_ipc_server_clients_get(Ecore_Ipc_Server *svr) s += 1; \ } -/** - * Sends a message to the given IPC server. - * - * The content of the parameters, excluding the @p svr parameter, is up to - * the client. - * - * @param svr The given IPC server. - * @param major Major opcode of the message. - * @param minor Minor opcode of the message. - * @param ref Message reference number. - * @param ref_to Reference number of the message this message refers to. - * @param response Requires response. - * @param data The data to send as part of the message. - * @param size Length of the data, in bytes, to send. - * @return Number of bytes sent. @c 0 is returned if there is an error. - * @ingroup Ecore_IPC_Server_Group - * @todo This function needs to become an IPC message. - * @todo Fix up the documentation: Make sure what ref_to and response are. - */ +/* FIXME: this needs to become an ipc message */ EAPI int ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int ref_to, int response, const void *data, int size) { @@ -622,28 +525,6 @@ ecore_ipc_server_send(Ecore_Ipc_Server *svr, int major, int minor, int ref, int return ret; } -/** - * Sets a limit on the number of clients that can be handled concurrently - * by the given server, and a policy on what to do if excess clients try to - * connect. - * Beware that if you set this once ecore is already running, you may - * already have pending CLIENT_ADD events in your event queue. Those - * clients have already connected and will not be affected by this call. - * Only clients subsequently trying to connect will be affected. - * @param svr The given server. - * @param client_limit The maximum number of clients to handle - * concurrently. -1 means unlimited (default). 0 - * effectively disables the server. - * @param reject_excess_clients Set to 1 to automatically disconnect - * excess clients as soon as they connect if you are - * already handling client_limit clients. Set to 0 - * (default) to just hold off on the "accept()" - * system call until the number of active clients - * drops. This causes the kernel to queue up to 4096 - * connections (or your kernel's limit, whichever is - * lower). - * @ingroup Ecore_Ipc_Server_Group - */ EAPI void ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char reject_excess_clients) { @@ -656,13 +537,6 @@ ecore_ipc_server_client_limit_set(Ecore_Ipc_Server *svr, int client_limit, char ecore_con_server_client_limit_set(svr->server, client_limit, reject_excess_clients); } -/** - * Sets the max data payload size for an Ipc message in bytes - * - * @param svr The given server. - * @param size The maximum data payload size in bytes. - * @ingroup Ecore_Ipc_Server_Group - */ EAPI void ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *svr, int size) { @@ -675,13 +549,6 @@ ecore_ipc_server_data_size_max_set(Ecore_Ipc_Server *svr, int size) svr->max_buf_size = size; } -/** - * Gets the max data payload size for an Ipc message in bytes - * - * @param svr The given server. - * @return The maximum data payload in bytes. - * @ingroup Ecore_Ipc_Server_Group - */ EAPI int ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *svr) { @@ -694,16 +561,6 @@ ecore_ipc_server_data_size_max_get(Ecore_Ipc_Server *svr) return svr->max_buf_size; } -/** - * Gets the IP address of a server that has been connected to. - * - * @param svr The given server. - * @return A pointer to an internal string that contains the IP address of - * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation. - * This string should not be modified or trusted to stay valid after - * deletion for the @p svr object. If no IP is known NULL is returned. - * @ingroup Ecore_Ipc_Server_Group - */ EAPI const char * ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr) { @@ -716,12 +573,6 @@ ecore_ipc_server_ip_get(Ecore_Ipc_Server *svr) return ecore_con_server_ip_get(svr->server); } -/** - * Flushes all pending data to the given server. Will return when done. - * - * @param svr The given server. - * @ingroup Ecore_Ipc_Server_Group - */ EAPI void ecore_ipc_server_flush(Ecore_Ipc_Server *svr) { @@ -766,29 +617,7 @@ ecore_ipc_server_flush(Ecore_Ipc_Server *svr) s += 1; \ } -/** - * @defgroup Ecore_IPC_Client_Group IPC Client Functions - * @ingroup Ecore_IPC_Library_Group - * - * Functions that deal with IPC client objects. - */ - -/** - * Sends a message to the given IPC client. - * @param cl The given IPC client. - * @param major Major opcode of the message. - * @param minor Minor opcode of the message. - * @param ref Reference number of the message. - * @param ref_to Reference number of the message this message refers to. - * @param response Requires response. - * @param data The data to send as part of the message. - * @param size Length of the data, in bytes, to send. - * @return The number of bytes sent. @c 0 will be returned if there is - * an error. - * @ingroup Ecore_IPC_Client_Group - * @todo This function needs to become an IPC message. - * @todo Make sure ref_to and response parameters are described correctly. - */ +/* FIXME: this needs to become an ipc message */ EAPI int ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int ref_to, int response, const void *data, int size) { @@ -833,12 +662,6 @@ ecore_ipc_client_send(Ecore_Ipc_Client *cl, int major, int minor, int ref, int r return ret; } -/** - * Retrieves the IPC server that the given IPC client is connected to. - * @param cl The given IPC client. - * @return The IPC server the IPC client is connected to. - * @ingroup Ecore_IPC_Client_Group - */ EAPI Ecore_Ipc_Server * ecore_ipc_client_server_get(Ecore_Ipc_Client *cl) { @@ -851,13 +674,6 @@ ecore_ipc_client_server_get(Ecore_Ipc_Client *cl) return cl->svr; } -/** - * Closes the connection and frees memory allocated to the given IPC - * client. - * @param cl The given client. - * @return Data associated with the client. - * @ingroup Ecore_IPC_Client_Group - */ EAPI void * ecore_ipc_client_del(Ecore_Ipc_Client *cl) { @@ -887,12 +703,6 @@ ecore_ipc_client_del(Ecore_Ipc_Client *cl) return data; } -/** - * Sets the IPC data associated with the given IPC client to @p data. - * @param cl The given IPC client. - * @param data The data to associate with the IPC client. - * @ingroup Ecore_IPC_Client_Group - */ EAPI void ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data) { @@ -905,12 +715,6 @@ ecore_ipc_client_data_set(Ecore_Ipc_Client *cl, const void *data) cl->data = (void *)data; } -/** - * Retrieves the data that has been associated with the given IPC client. - * @param cl The given client. - * @return The data associated with the IPC client. - * @ingroup Ecore_IPC_Client_Group - */ EAPI void * ecore_ipc_client_data_get(Ecore_Ipc_Client *cl) { @@ -923,13 +727,6 @@ ecore_ipc_client_data_get(Ecore_Ipc_Client *cl) return cl->data; } -/** - * Sets the max data payload size for an Ipc message in bytes - * - * @param cl The given client. - * @param size The maximum data payload size in bytes. - * @ingroup Ecore_Ipc_Client_Group - */ EAPI void ecore_ipc_client_data_size_max_set(Ecore_Ipc_Client *cl, int size) { @@ -942,13 +739,6 @@ ecore_ipc_client_data_size_max_set(Ecore_Ipc_Client *cl, int size) cl->max_buf_size = size; } -/** - * Gets the max data payload size for an Ipc message in bytes - * - * @param cl The given client. - * @return The maximum data payload size in bytes on success, @c -1 on failure. - * @ingroup Ecore_Ipc_Client_Group - */ EAPI int ecore_ipc_client_data_size_max_get(Ecore_Ipc_Client *cl) { @@ -961,17 +751,6 @@ ecore_ipc_client_data_size_max_get(Ecore_Ipc_Client *cl) return cl->max_buf_size; } -/** - * Gets the IP address of a client that has been connected to. - * - * @param cl The given client. - * @return A pointer to an internal string that contains the IP address of - * the connected server in the form "XXX.YYY.ZZZ.AAA" IP notation. - * This string should not be modified or trusted to stay valid after - * deletion for the @p cl object. If no IP is known @c NULL is - * returned. - * @ingroup Ecore_Ipc_Client_Group - */ EAPI const char * ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl) { @@ -984,12 +763,6 @@ ecore_ipc_client_ip_get(Ecore_Ipc_Client *cl) return ecore_con_client_ip_get(cl->client); } -/** - * Flushes all pending data to the given client. Will return when done. - * - * @param cl The given client. - * @ingroup Ecore_Ipc_Client_Group - */ EAPI void ecore_ipc_client_flush(Ecore_Ipc_Client *cl) { @@ -1002,11 +775,6 @@ ecore_ipc_client_flush(Ecore_Ipc_Client *cl) ecore_con_client_flush(cl->client); } -/** - * Returns if SSL support is available - * @return 1 if SSL is available, 0 if it is not. - * @ingroup Ecore_Con_Client_Group - */ EAPI int ecore_ipc_ssl_available_get(void) {