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

ParameterDescription
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

ParameterDescription
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

ParameterDescription
booleanBy default, this is false.
  • True - deletes the folder and all its content recursively.
  • False - if the directory is empty it shall be removed.
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

ParameterDescription
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

ParameterDescription
Rawbytes/stringdata to write of type text string or kony.types.RawBytes
Append (optional)
  • true to append the data. Default is false, that means overrides the content.

    • 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