===== Javascript binding API - Ecore Files =====
[[:develop:legacy:api:javascript:ecore|Back to the JS Ecore page]]
**DRAFT**
The File module provides a large number of functions to work with files, directories and downloads.
==== Constants ====
=== Events ===
When monitoring a file or a directory, these constants are used:
* ''efl.Ecore.File.EVENT_NONE'' - No event.
* ''efl.Ecore.File.EVENT_CREATED_FILE'' - Created file event.
* ''efl.Ecore.File.EVENT_CREATED_DIRECTORY'' - Created directory event.
* ''efl.Ecore.File.EVENT_DELETED_FILE'' - Deleted file event.
* ''efl.Ecore.File.EVENT_DELETED_DIRECTORY'' - Deleted directory event.
* ''efl.Ecore.File.EVENT_SELF'' - Deleted monitored directory event.
* ''efl.Ecore.File.EVENT_MODIFIED'' - Modified file or directory event.
* ''efl.Ecore.File.EVENT_CLOSED'' - Closed file event.
=== Progress ===
These constants are used to handle the progress of a download action.
* ''efl.Ecore.File.PROGRESS_CONTINUE'' - Continue the download.
* ''efl.Ecore.File.PROCESS_ABORT'' - Abort the download.
==== Functions ====
=== abortAllDownloads() ===
Syntax
efl.Ecore.File.abortAllDownloads();
Abort all downloads.
This function aborts all the downloads that have been started by ''efl.Ecore.File.download''. It loops over the started downloads and call ''abort()'' for each of them. To abort only one specific download operation, call ''abort()'' directly on the download wrapper object.
=== addMonitor(path, callback) ===
Syntax
function mycallback(monitor, event, path) { ... }
var monitor = efl.Ecore.File.addMonitor(path, mycallback);
Parameters
* path - The path to monitor.
* callback - The function to call on changes.
Return type
* object - An object wrapping the new monitor.
* null - If it was not possible to create the monitor.
This function monitors path. If path is ''null'', or is an empty string, or none of the notify methods (Inotify, Windows notification or polling) is available, or if the path does not exist the function returns ''null''. Otherwise, it returns a newly allocated ''Monitor'' object and the monitoring begins. When one of the ''efl.Ecore.File.EVENT_*'' events is notified, the callback is called. Call ''del()'' on the monitor object to stop the monitoring.
=== availableDownloadProtocol(protocol) ===
Syntax
var isAvailable = efl.Ecore.File.availableDownloadProtocol(protocol);
Parameters
* protocol - The name of the desired protocol
Return type
* boolean - Whether the protocol is available or not.
This function returns ''true'' if protocol is supported, ''false'' otherwise. protocol can be ''http://'', ''ftp://'' or ''file:/\/ ''. Ecore.File must be compiled with CURL to handle http and ftp protocols.
=== canExec(file) ===
Syntax
var canExec = efl.Ecore.File.canExec(file)
Parameters
* file - The name of the file.
Return value
* boolean - ''true'' if the file can be executed, ''false'' otherwise.
This function returns ''true'' if file can be executed, ''false'' otherwise.
=== canRead(file) ===
Syntax
var canRead = efl.Ecore.File.canRead(file)
Parameters
* file - The name of the file.
Return value
* boolean - ''true'' if the file is readable, ''false'' otherwise.
This function returns ''true'' if file can be read, ''false'' otherwise.
=== canWrite(file) ===
Syntax
var canWrite = efl.Ecore.File.canWrite(file)
Parameters
* file - The name of the file.
Return value
* boolean - ''true'' if the file is writable, ''false'' otherwise.
This function returns ''true'' if file can be written, ''false'' otherwise.
=== cp(src, dst) ===
Syntax
efl.Ecore.File.cp(src, dst)
Parameters
* src - The name of the source file.
* dst - The name of the destination file.
Return value
* boolean - ''true'' on success, ''false'' otherwise.
This function copies src to dst. If the absolute path name of src and dst can not be computed, or if they are equal, or if the copy fails, the function returns ''false'', otherwise it returns ''true''.
=== efl.Ecore.File.download(url, dst, completion_cb, progress_cb [, headers]) ===
Syntax
function completion_cb(file, status) { ... };
function progress_cb(file, dltotal, dlnow, ultotal, ulnow) { ... };
efl.Ecore.File.download(url, dst, completion_cb, progress_cb);
headers = {...};
efl.Ecore.File.download(url, dst, completion_cb, progress_cb, headers);
Parameters
* url - The complete url to download.
* dst - The local file to save the downloaded to.
* completion_cb - A callback called on download complete.
* progress_cb - A callback called during the download operation.
* headers - Optional object with set of headers to the download operation.
Return value
* boolean - ''true'' if the download start or ''false'' on failure.
This function starts the download of the URL ''url'' and saves it to ''dst''. ''url'' must provide the protocol, including 'http://', 'ftp://' or 'file:/\/'. ''efl.Ecore.File'' must be compiled with CURL to download using http and ftp protocols. If ''dst'' is ill-formed, or if it already exists, the function returns ''false''. When the download is complete, the callback ''completion_cb'' is called and data is passed to it. The status parameter of completion_cb will be filled with the status of the download (200, 404,...). The 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 (or ''efl.Ecore.File.PROGRESS_CONTINUE'' 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'. Similarly ''efl.Ecore.File.abortAllDownloads()'' can be used to abort all download operations.
The optional ''headers'' parameters contain additional headers to control the download operation.
This function returns ''true'' if the download starts, ''false'' otherwise.
=== environmentTmp() ===
Syntax
var tmpDir = efl.Ecore.File.environmentTmp();
Return type
* string -A temporary string to the content refered by TMPDIR on this system.
Return the content of the environment refered as TMPDIR on this system.
The result of this call is highly system dependent and you better use it instead of the naive getenv("TMPDIR").
=== escapeName(filename) ===
Syntax
var name = efl.Ecore.File.escapeName(filename)
Parameters
* filename - The file name.
Return value
* string - 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, NULL is returned.
=== exists(file) ===
Syntax
var exists = efl.Ecore.File.exists(file)
Parameters
* file - The name of the file.
Return value
* boolean - ''true'' if the file exists, ''false'' otherwise.
This function returns ''true'' if file exists on local filesystem, ''false'' otherwise.
=== existsPathDir(in_dir) ===
Syntax
var exists = efl.Ecore.File.path_dir_exists(in_dir)
Parameters
* in_dir - The name of the directory to search in PATH.
Return value
* boolean - ''true'' if the directory exist in PATH, ''false'' otherwise.
This function checks if in_dir is in the environment variable PATH. If in_dir is NULL, or if PATH is empty, or in_dir is not in PATH, the function returns ''false'', otherwise it returns ''true''.
=== getAppExe(app) ===
Syntax
var exe = efl.Ecore.File.getAppExe(app)
Parameters
* app - The application command, with parameters.
Return value
* string - The executable from app as a newly allocated string. Arguments are removed and escape characters are handled. If app is NULL, or on failure, the function returns NULL.
The executable from app as a newly allocated string. Arguments are removed and escape characters are handled. If app is NULL, or on failure, the function returns NULL. When not needed anymore, the returned value must be freed.
=== getDir(file) ===
Syntax
var dir = efl.Ecore.File.getDir(file)
Parameters
* file - The name of the file.
Return value
* string - The directory name.
This function returns the directory where file resides as anewly allocated string. If file is NULL or on error, this function returns NULL.
=== getFile(path) ===
Syntax
var filename = efl.Ecore.File.getFile(path)
Parameters
* path - The complete path.
Return value
* string - The file name.
Get the filename from a given path.
=== init() ===
Syntax
var status = efl.Ecore.File.init()
Return type
* number - 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.
=== installedApp(exe) ===
Syntax
var isInstalled = efl.Ecore.File.installedApp(exe);
Parameters
* exe - The name of the application
Return value
* boolean - ''true'' if the exe is in PATH and is executable, ''false'' otherwise.
This function checks if ''exe'' exists in PATH and is executable. If exe is NULL or is not executable, the function returns ''false'', otherwise it returns ''true''.
=== isDir(file) ===
Syntax
var isDir = efl.Ecore.File.isDir(file)
Parameters
* file - The name of the file.
Return value
* boolean - ''true'' if the file exists and is a directory, ''false'' otherwise.
This function returns ''true'' if file exists exists and is a directory on local filesystem, ''false'' otherwise.
=== isEmptyDir(dir) ===
Syntax
var isEmptyDir = efl.Ecore.File.isEmptyDir(dir);
Parameters
* dir - The name of the directory to check.
Return value
* number - 1 if directory is empty, 0 if it has at least one file or -1 in case of errors.
This functions checks if dir is empty. The '.' and '..' files will be ignored. If dir is empty, 1 is returned, if it contains at least one file, 0 is returned. On failure, -1 is returned.
=== listApp() ===
Syntax
var apps = efl.Ecore.File.listApp(void);
Return value
* array of strings - An array 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 NULL.
=== ls(dir) ===
Syntax
var entries = efl.Ecore.File.ls(dir)
Parameters
* dir - The name of the directory to list
Return value
* array of strings - Return a array 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 dir. The list will be sorted with the native 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, NULL is returned.
=== mkdir(dir) ===
Syntax
var created = efl.Ecore.File.mkdir(dir)
Parameters
* dir - The name of the directory to create
Return value
* boolean - ''true'' on successful creation, ''false'' otherwise.
This function creates the directory dir, with the mode ''S_IRUSR | S_IWUSR | S_IXUSR | S_IRGRP | S_IXGRP | S_IROTH | S_IXOTH'' on UNIX (mode is unused on Windows). On success, it returns ''true'', ''false'' otherwise.
=== mkdirs(dirs) ===
Syntax
var numCreated = efl.Ecore.File.mkdirs(dirs)
Parameters
* dirs - The list of directories.
Return value
* number - The number of successful directories created, -1 if dirs is NULL.
This function creates all the directories that are in the null terminated array dirs. The function loops over the directories and call ''efl.Ecore.File.mkdir()''. This function returns -1 if dirs is NULL, otherwise if returns the number of suceesfully created directories.
=== mkpath(path) ===
Syntax
var created = efl.Ecore.File.mkpath(path)
Parameters
* path - The path to create
Return value
* boolean - ''true'' on success, ''false'' otherwise.
This function creates path and all the subdirectories it contains. The separator is '/' or '\'. If path exists, this function returns ''true'' immediately. It returns ''true'' on success, ''false'' otherwise.
=== mkpaths(paths) ===
Syntax
var numCreated = efl.Ecore.File.mkpaths(paths)
Parameters
* paths - list of paths.
Return value
* number - number of successful paths created, -1 if paths is NULL.
This function creates all the directories that are in the null terminated array paths. The function loops over the directories and calls ''efl.Ecore.File.mkpath()'', hence on Windows, '\' must be replaced by '/' before calling that function. This function returns -1 if paths is NULL. Otherwise, if returns the number of successfully created directories.
=== mkstemp(template) ===
Syntax
var path = efl.Ecore.file.mkstemp(template)
Parameters
* template - The template for the path, ending with ''XXXXXX''.
Return type
* string - The path of the new temporary file.
Creates a temporary file with filename based on ''template''.
=== mksubdirs(base, subdirs) ===
Syntax
var numCreated = efl.Ecore.File.mksubdirs(base, subdirs)
Parameters
* base - The base directory to act on.
* subdirs - The list of directories.
Return value
* number - number of successful directories created, -1 on failure.
This function creates all the directories that are in the array subdirs in the base directory. If base does not exist, it will be created. The function loops over the directories and call ''efl.Ecore.File.mkdir()''. The whole path of the directories must exist. So if base/a/b/c wants to be created, subdirs must contain "a", "a/b" and "a/b/c", in that order. This function returns -1 if subdirs or base are NULL, or if base is empty ("\0"). It returns 0 is base is not a directory or invalid, or if it can't be created. Otherwise if returns the number of suceesfully created directories.
=== modTime() ===
Syntax
var time = efl.Ecore.File.modTime(file)
Parameters
* file - The name of the file.
Return value
* number - Return the time of the last data modification, or 0 on failure.
This function returns the time of the last modification of file. On failure, it returns 0.
=== mv(src, dst) ===
Syntax
var moved = efl.Ecore.File.mv(src, dst)
Parameters
* src - The name of the source file.
* dst - The name of the destination file.
Return value
* boolean - ''true'' on success, ''false'' otherwise.
This function moves src to dst. It returns ''true'' on success, ''false'' otherwise.
=== readlink(lnk) ===
Syntax
var path = efl.Ecore.File.readlink(lnk)
Parameters
* lnk - The name of the link.
Return value
* string - The path pointed by link or NULL.
This function returns the path pointed by link as a newly allocated string. This function does not work on Windows. On failure, the function returns NULL.
=== realPath(file) ===
Syntax
var path = efl.Ecore.File.realPath(file)
Parameters
* file - The file path.
Return value
* string - The canonicalized absolute pathname or an empty string on failure.
This function returns the absolute path name of file as a newly allocated string. If file is NULL, or on error, this function returns an empty string. Otherwise, it returns the absolute path name.
=== remove(file) ===
Syntax
var removed = efl.Ecore.File.remove(file)
Parameters
* file - The name of the file or directory to delete.
Return value
* boolean - ''true'' on success, ''false'' otherwise.
This function removes file. It returns ''true'' on success, ''false'' otherwise.
=== rmdir(dir) ===
Syntax
var removed = efl.Ecore.File.rmdir(dir)
Parameters
* dir - The name of the directory to delete.
Return value
* boolean - ''true'' on success, ''false'' otherwise.
This function deletes dir. It returns ''true'' on success, ''false'' otherwise.
=== rmRecursive(dir) ===
Syntax
var removed = efl.Ecore.File.rmRecursive(dir)
Parameters
* dir - The name of the directory to delete.
Return value
* boolean - ''true'' on success, ''false'' otherwise.
This function delete dir and all its contents. If dir is a link only the link is removed. It returns ''true'' on success, ''false'' otherwise.
=== shutdown() ===
Syntax
var status = efl.Ecore.File.shutdown();
Return type
* number - 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 ''efl.Ecore.File.init()''. In that case it shuts down all the services it uses.
=== size(file) ===
Syntax
var size = efl.Ecore.File.size(file)
Parameters
* file - The name of the file.
Return value
* number - Return the size of the file in bytes, or 0 on failure.
This function returns the size of file in bytes. On failure, it returns 0.
=== stripExtension(path) ===
Syntax
var stripped_path = efl.Ecore.File.strip_ext(path)
Parameters
* path - The name of the file.
Return value
* string - A newly allocated string with the extension stripped out or NULL on errors.
This function removes the extension from path and returns the result as a newly allocated string. If path is NULL, or on failure, the function returns NULL.
=== symlink(src, dest) ===
Syntax
var linked = efl.Ecore.File.symlink(src, dest)
Parameters
* src - The name of the file to link.
* dest - The name of link.
Return value
* boolean - ''true'' on success, ''false'' otherwise.
This function create the symbolic link dest of src. This function does not work on Windows. It returns ''true'' on success, ''false'' otherwise.
=== unlink(file) ===
Syntax
efl.Ecore.File.unlink(file)
Parameters
* file - The name of the file to delete.
Return value
* boolean - ''true'' on success, ''false'' otherwise.
This function deletes file. It returns ''true'' on success, ''false'' otherwise.
==== Methods ====
=== download.abort() ====
Syntax
downloadObj.abort();
Aborts a single download.