Wiki page file changed with summary [Move Javascript docs to legacy API] by Andrew Williams

This commit is contained in:
Andrew Williams 2017-10-20 11:07:29 -07:00 committed by apache
parent 07d114e77a
commit 56812d6120
1 changed files with 746 additions and 0 deletions

View File

@ -0,0 +1,746 @@
===== Javascript binding API - Ecore Files =====
[[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
<code javascript>
efl.Ecore.File.abortAllDownloads();
</code>
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
<code javascript>
function mycallback(monitor, event, path) { ... }
var monitor = efl.Ecore.File.addMonitor(path, mycallback);
</code>
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
<code javascript>
var isAvailable = efl.Ecore.File.availableDownloadProtocol(protocol);
</code>
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
<code javascript>
var canExec = efl.Ecore.File.canExec(file)
</code>
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
<code javascript>
var canRead = efl.Ecore.File.canRead(file)
</code>
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
<code javascript>
var canWrite = efl.Ecore.File.canWrite(file)
</code>
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
<code javascript>
efl.Ecore.File.cp(src, dst)
</code>
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
<code javascript>
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);
</code>
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
<code javascript>
var tmpDir = efl.Ecore.File.environmentTmp();
</code>
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.
<note important>
The result of this call is highly system dependent and you better use it instead of the naive getenv("TMPDIR").
</note>
=== escapeName(filename) ===
Syntax
<code javascript>
var name = efl.Ecore.File.escapeName(filename)
</code>
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
<code javascript>
var exists = efl.Ecore.File.exists(file)
</code>
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
<code javascript>
var exists = efl.Ecore.File.path_dir_exists(in_dir)
</code>
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
<code javascript>
var exe = efl.Ecore.File.getAppExe(app)
</code>
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
<code javascript>
var dir = efl.Ecore.File.getDir(file)
</code>
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
<code javascript>
var filename = efl.Ecore.File.getFile(path)
</code>
Parameters
* path - The complete path.
Return value
* string - The file name.
Get the filename from a given path.
=== init() ===
Syntax
<code javascript>
var status = efl.Ecore.File.init()
</code>
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
<code javascript>
var isInstalled = efl.Ecore.File.installedApp(exe);
</code>
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
<code javascript>
var isDir = efl.Ecore.File.isDir(file)
</code>
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
<code javascript>
var isEmptyDir = efl.Ecore.File.isEmptyDir(dir);
</code>
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
<code javascript>
var apps = efl.Ecore.File.listApp(void);
</code>
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
<code javascript>
var entries = efl.Ecore.File.ls(dir)
</code>
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
<code javascript>
var created = efl.Ecore.File.mkdir(dir)
</code>
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
<code javascript>
var numCreated = efl.Ecore.File.mkdirs(dirs)
</code>
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
<code javascript>
var created = efl.Ecore.File.mkpath(path)
</code>
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
<code javascript>
var numCreated = efl.Ecore.File.mkpaths(paths)
</code>
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
<code javascript>
var path = efl.Ecore.file.mkstemp(template)
</code>
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
<code javascript>
var numCreated = efl.Ecore.File.mksubdirs(base, subdirs)
</code>
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
<code javascript>
var time = efl.Ecore.File.modTime(file)
</code>
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
<code javascript>
var moved = efl.Ecore.File.mv(src, dst)
</code>
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
<code javascript>
var path = efl.Ecore.File.readlink(lnk)
</code>
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
<code javascript>
var path = efl.Ecore.File.realPath(file)
</code>
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
<code javascript>
var removed = efl.Ecore.File.remove(file)
</code>
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
<code javascript>
var removed = efl.Ecore.File.rmdir(dir)
</code>
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
<code javascript>
var removed = efl.Ecore.File.rmRecursive(dir)
</code>
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
<code javascript>
var status = efl.Ecore.File.shutdown();
</code>
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
<code javascript>
var size = efl.Ecore.File.size(file)
</code>
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
<code javascript>
var stripped_path = efl.Ecore.File.strip_ext(path)
</code>
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
<code javascript>
var linked = efl.Ecore.File.symlink(src, dest)
</code>
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
<code javascript>
efl.Ecore.File.unlink(file)
</code>
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
<code javascript>
downloadObj.abort();
</code>
Aborts a single download.