kony.io.File Namespace
The kony,io.File namespace provides functions and properties for doing various operations related on files, such as copying them, renaming them , deleting them, and so on.
Overview
Your app can create a File
object to represent files in the device's file system and perform common operations on them. To create a new File
object , your app calls the kony.io.File
function. Alternatively, it can use the kony.io.FileSystem.getFile function to get an instance of a File
object.
var myfile = new kony.io.File("myfile.txt");
or
var myfile = kony.io.FileSystem.getFile("myfile.txt")
File Properties:Name | Description |
---|---|
name: [type: String, ReadOnly] | Name of the file or directory |
fullPath: [type: String, ReadOnly] | Full absolute path of the file or directory |
parent: [type:kony.io.File, ReadOnly] | Returns the parent directory of this file.
This property may return nil or a File object which can neither Readable or Writable, especially in case of Folders which are not accessible by the given Application context |
readable: [type: Boolean, ReadOnly] | Returns true if this file is readable |
writable: [type: Boolean, ReadOnly] | Returns true if this file is writable |
modificationTime: [type:Number, ReadOnly] | Returns the last modification time of the file in UTC |
size: [type:Number, ReadOnly | Returns the size of a file in number of bytes. |
The following function is often used in conjunction with the RawBytes object to read data of type RawBytes.
Functions
The kony.io.File namespace contains these functions: To use the copyTo, moveTo, remove, rename, createFile, createDirectory, read, and write File APIs, your app needs runtime permission from the end-user (to perform any of the action correspondent to a file). If you call any API without obtaining the permission, platforms automatically pops up a system permission dialog box with "Allow" and "Deny" options, asking the end-user to grant permission. This is applicable only for the Android platform.
If the end-user taps the "Allow" option, platform proceeds to access the underlying OS API. If the end-user taps the "Deny" option, the PermissionError exception is thrown with the 2300 error code, that means permission is denied.
copyTo API copies a file to the given destination path.
Syntax
kony.io.File.copyTo(String path, String newName);
Input Parameters
Parameter | Description |
---|---|
Path | path to the destination directory. |
newName (optional) | New name of the file/directory. Defaults to current name if unspecified. |
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var copyToLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir1"; var newFile = new kony.io.File(origFileLoc).copyTo(copyToLoc, "NewNameForCopy.txt");
Return Values
Kony.io.File returns a handle to the File object pointing to the destination file, if successful. If failure, then returns null.
Exceptions
None
Platform Availability
- iOS
- Android
The createDirectory API creates a directory on the file system represented by this file object.
Syntax
kony.io.File.createDirectory();
Input Parameters
None
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var dirLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir1"; var myDir = new kony.io.File(dirLoc).createDirectory();
Return Values
Boolean – true if the creation of directory is successful. False if directory already exists or could not be created.
Exceptions
None
Platform Availability
- iOS
- Android
The createFile API creates a file on the file system represented by this file object.
Syntax
kony.io.File.createFile();
Input Parameters
None
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var fileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFileToCopy.txt"; var myFile = new kony.io.File(fileLoc).createFile();
Return Values
Boolean – true if the creation of file is successful. False if file already exists or could not be created.
Exceptions
None
Platform Availability
- iOS
- Android
The exist API checks, if the file or directory exists on the file system represented by this file object.
Syntax
kony.io.File.exists();
Input Parameters
None
Example
var copiedFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir1" + constants.FILE_PATH_SEPARATOR + "NewNameForCopy.txt"; if (new kony.io.File(copiedFileLoc).exists()) { kony.print("copy of file was successful"); } else { kony.print("copy of file failed"); }
Return Values
Boolean – true if the file or directory exists on file system.
Exceptions
None
Platform Availability
- iOS
- Android
The getFilesList API returns kony.io.FileList object representing the files and directories available under this file object directory.
Syntax
kony.io.File.getFilesList();
Input Parameters
None
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var myDirLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir416"; var myDirName = new kony.io.File(myDirLoc); var createDir = myDirName.createDirectory(); var fileListLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir416"; var filesList = new kony.io.File(fileListLoc).getFilesList(); if (filesList.length === 0) { kony.print("getFilesList successful for zero files"); } else { kony.print("getFilesList failed for zero files"); }
Return Values
kony.io.FileList – FileList object or null if this File is not identified as a directory.
Exceptions
None
Platform Availability
- iOS
- Android
The isDirectory API checks, if this object represents a directory file on the file system.
Syntax
kony.io.File.isDirectory();
Input Parameters
None
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var dirLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir765"; var myDir = new kony.io.File(dirLoc); try { var isDirec = new kony.io.File(dirLoc).isDirectory(); if (isDirec) { kony.print("isDirectory True for nonExistent Directory"); } } catch (err) { kony.print("isDirec doesn't work over nonExistent directory"); }
Return Values
Boolean – true, if this file object represents a directory, false otherwise.
Exceptions
None
Platform Availability
- iOS
- Android
The isFile API checks, if this object represents a typical file on the file system but not a directory.
Syntax
kony.io.File.isFile();
Input Parameters
None
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFile244.txt"; var myFileName = new kony.io.File(myFileLoc); try { var isFileThere = new kony.io.File(myFileLoc).isFile(); if (isFileThere) { kony.print("isFile true for nonExistent File"); } else { kony.print("isFile false for nonExistent File"); } } catch (err) { kony.print("isFile doesn't work on non-existent files"); }
Return Values
Boolean – true if this file object represents a file, false otherwise.
Exceptions
None
Platform Availability
- iOS
- Android
The moveTo API moves a file to the given destination path.
Syntax
kony.io.File.moveTo(String path, String newname);
Input Parameters
Parameter | Description |
---|---|
Path | path to the destination directory. |
newName (optional) | New name of the file/directory. Defaults to current name, if unspecified. |
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var dirLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myDir25"; var myDir = new kony.io.File(dirLoc).createDirectory(); var fileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFileToMove25.txt"; var myFile = new kony.io.File(fileLoc).createFile(); var newFile = new kony.io.File(fileLoc).moveTo(mainLoc); if (newFile !== null) { kony.print("moving to same loc with same name was successful"); } else { kony.print(" can't move to same loc with same name"); }
Return Values
Kony.io.File – returns a handle to File object pointing to destination file on success. Returns null on failure.
Exceptions
None
Platform Availability
- iOS
- Android
The read API returns the kony.types.RawBytes of this file.
Syntax
kony.io.File.read();
Input Parameters
None
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFile313.txt"; var myFileName = new kony.io.File(myFileLoc); try { var reading = new kony.io.File(myFileLoc).read(); kony.print(reading); if (reading === null) { kony.print("null is coming from reading i.e can't be done"); } else { kony.print("reading can be done on NonExistentFile"); } } catch (err) { kony.print("can't try read on nonExistent File causes Error"); }
Return Values
kony.types.RawBytes – rawbytes representing the content of the file.Returns null in case of non existent file.
Exceptions
None
Platform Availability
- iOS
- Android
NOTE: RawBytes will hold a handle of File object that it represents. The file content is not actually loaded into memory.
The remove API deletes a file or a directory.
Syntax
remove(boolean, deleteRecursive);
Input Parameters
Parameter | Description |
---|---|
boolean | By default, this is false.
|
deleteRecursive (optional) | Ignored in case of a file. |
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFileToMove12.txt"; var myFile = new kony.io.File(myFileLoc); myFile.createFile(); myFile.remove(true); if (new kony.io.File(myFileLoc).exists()) { kony.print("removing file failed"); } else { kony.print("removing file was successful"); }
Return Values
None
Exceptions
None
Platform Availability
- iOS
- Android
The rename API renames a file or a directory.
Syntax
kony.io.File.rename(String newname);
Input Parameters
Parameter | Description |
---|---|
newname | new name for a file or a directory. |
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFileToReName7578.txt"; var myFile = new kony.io.File(myFileLoc).createFile(); var newFile = new kony.io.File(myFileLoc).rename("myFileToReName7577"); if (newFile) { kony.print("renaming file with name successfull with extension"); } else { kony.print("renaming file failed for name without Extension"); }
Return Values
Boolean – If successful, then boolean value is true,. Boolean value is false, if invalid file name or if the destination is a different directory than the current file.
Exceptions
None
Platform Availability
- iOS
- Android
The write API writes the given content into the file.
Syntax
kony.io.File.write(rawbytes/string, append);
Input Parameters
Parameter | Description |
---|---|
Rawbytes/string | data to write of type text string or kony.types.RawBytes |
Append (optional) |
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFile376.txt"; var myFileName = new kony.io.File(myFileLoc).createFile(); try { var writing = new kony.io.File(myFileLoc).write("How are you?"); if (writing !== null) { kony.print("writing can be done on Non Existing Files"); } else { kony.print("writing on nonExisting file returns null"); } } catch (err) { kony.print("can't try write on NonExistingFile, causes Error"); }
Return Values
Boolean – true if success, false otherwise.
Exceptions
None
Platform Availability
- iOS
- Android