Back to the JS Ecore page

DRAFT

The File module provides a large number of functions to work with files, directories and downloads.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Syntax

downloadObj.abort();

Aborts a single download.