kony.io.FileSystem Namespace
The kony.io.FileSystem namespace includes APIs to create, read, and navigate through the device file system.
Information about the kony.io.FileSystem namespace is presented in the following topic.
Functions
The kony.io.FileSystem namespace contains the following functions.
This API provides the ability to browse and select files from your local system.
Syntax
kony.io.FileSystem.browse(browseConfig,browseCallBack);
Input Parameters
Parameter | Description |
---|---|
browseConfig [String] - Mandatory | Configuration params which is a simple JSON object of key value pairs, that drive the possible options during the browse. Currently the following keys are supported in the configuration:
|
browseCallBack [Object] - Mandatory | The callback function. |
Example
function selectBtn_onClick_seq0() { // Event on button click var config = { selectMultipleFiles: true, filter: ["image/png", "image/jpeg"] }; kony.io.FileSystem.browse(config, selectedFileCallback); }
Return Values
None
Platform Availability
- Desktop Web
This API copies a bundled file from the application binary to the specified destination path on the device. While copying the pre-bundled file, the destination file name can be different from the source.
Syntax
kony.io.FileSystem.copyBundledRawFileTo (String rawFileName, String destFilePath);
Input Parameters
Parameter | Description |
---|---|
rawFileName [String] | Specify the file name with the extension of a pre-bundled raw file that you want to copy. |
destFilePath [String] | Specify the absolute file path along with the file name and extension (if any) where you want to copy the pre-bundled file. In this parameter, the destination file name can be different from the source. |
Example
//The destination file name can be different from the source. var destFilePath = kony.io.FileSystem.getDataDirectoryPath()+ "/Destinationfile.pdf"; var fileObj = null; try { var file = new kony.io.File(destFilePath); //copyBundledRawFileTo API overrides the destination file with new one. //Hence check before copying if (!file.exists()) { var fileObj = kony.io.FileSystem.copyBundledRawFileTo(“Sourcefile.pdf”, destFilePath); } else { fileObj = file; alert("File is already available"); return; } } catch (e) { kony.print(“Exception“ + e); }
Remarks
- When the app functionality is tested in functional preview application, the kony.io.FileSystem.copyBundledRawFileTo API looks for the file in the child app (Downloaded test application). If not found, searches for the same file in the parent app (Functional Preview application).
- The kony.io.FileSystem.copyBundledRawFileTo API overrides the destination file with new one if any file exists with the same name at the destination path.
For more information about bundling the files in the application binary, refer to the Pre bundling the Files topic.
Return Values
Kony.io.File returns a handle to the File object pointing to the destination file, if successful. If failure, then throws appropriate exception.
Exceptions
Error Code | Error Message |
---|---|
100 | Source file not found. |
100 | Invalid Destination. |
101 | Invalid number of arguments. |
106 | Unknown error. |
Platform Availability
- iOS
- Android
This API retrieves the root path of an app group.
Syntax
kony.io.FileSystem.getAppGroupDirectoryPath(appGroupID);
Parameters
Parameter | Description |
---|---|
appGroupID | Holds a string containing the unique ID of the app group. |
Example
var appGroupPath = kony.io.FileSystem.getAppGroupDirectoryPath("String");
Return Values
A string containing the fully-qualified path to the root directory of the app group.
Platform Availability
- iOS only
The getApplicationDirectoryPath API returns the application directory path.
Syntax
kony.io.FileSystem.getApplicationDirectoryPath();
Input Parameters
None
Example
var appDirectoryPath = kony.io.FileSystem.getApplicationDirectoryPath();
Return Values
String
Exceptions
None
Platform Availability
- iOS
The getCacheDirectoryPath API returns the application's cache directory path.
Syntax
kony.io.FileSystem.getCacheDirectoryPath()
Input Parameters
None
Example
var cacheDirectoryPath = kony.io.FileSystem.getCacheDirectoryPath();
Return Values
String
Exceptions
None
Platform Availability
- All native platforms
- Desktop Web
This API returns the application's database directory path (from application's private file system) where kony.db APIs access the database files.
This API is useful in accessing the pre-bundled SQLite database file. You need to copy the pre-bundled database file to the directory path returned by the kony.io.FileSystem.getDatabaseDirectoryPath API, using the kony.io.FileSystem.copyBundledRawFileTo API. You can then use the kony.db.openDatabase API to open the SQLite database files after copying.
Syntax
kony.io.FileSystem.getDatabaseDirectoryPath();
Input Parameters
None
Example
//Example for opening the pre-bundled database //The destination file name can be different from the source. var destFilePath = kony.io.FileSystem.getDatabaseDirectoryPath() + ”test.db”; var fileObj = null; try { var file = new kony.io.File(destFilePath); //copyBundledRawFileTo API overrides the destination file with new one. //Hence check before copying if (!file.exists()) { fileObj = kony.io.FileSystem.copyBundledRawFileTo(dbName, destFilePath); } else { fileObj = file; alert("File is already available"); return; } } catch (e) { kony.print(“Exception“ + e); } if (fileObj == null) { kony.print(“Copy failed”); } else { kony.print(“Copy Success”); } dbObject = kony.db.openDatabase("test.db", "1.0", "Prebundled SQL Database", 5 * 1024 * 1024);
Return Values
Application's database directory path in the form of String.
For Functional Preview, the path returned by the getDatabaseDirectoryPath API points to the child application on your device. This feature is available on iOS and Android devices.
Exceptions
None
Platform Availability
- iOS
- Android
This API returns the application’s data directory path.
Syntax
kony.io.FileSystem.getDataDirectoryPath();
Input Parameters
None
Example
var dataDirectoryPath = kony.io.FileSystem.getDataDirectoryPath();
Return Values
String
For Functional Preview, the path returned by the getDataDirectoryPath API points to the child application on your device. This feature is available on iOS and Android devices.
Exceptions
None
Platform Availability
- Applicable for all native platforms, except Desktop Web.
The getExternalCacheDir API returns the absolute path to the directory on the primary shared or external storage device where the application can store its cached files.
Syntax
kony.io.FileSystem.getExternalCacheDir();
Example
var dirPath = kony.io.FileSystem.getExternalCacheDir();
Return Values
String
NOTE: If the shared storage is not available, this API returns a null
value.
Exceptions
None
Platform Availability
- Android
The getExternalCacheDirs API returns the absolute paths to the application-specific directories on all the shared or external storage devices where the application can store its cached files.
Syntax
kony.io.FileSystem.getExternalCacheDirs();
Example
var dirPath = kony.io.FileSystem.getExternalCacheDirs();
Return Values
Array of Strings
NOTE: If the shared storage is not available, this API returns a null
value.
Exceptions
None
Platform Availability
- Android
NOTE: If your device runs on Android versions before Android KitKat, the kony.io.FileSystem.getExternalFilesDirs API returns the same result as the kony.io.FileSystem.getExternalFilesDir API.
The getExternalFilesDir API returns the absolute path to the directory on the primary shared or external storage device where the application can store its persistent files.
NOTE:
- From API level 29, apps do not require additional permissions to read and write files to this directory.
- The files in this directory are internal to the application, and are deleted when you uninstall the app.
Syntax
kony.io.FileSystem.getExternalFilesDir(type);
Input Parameters
Parameters | Description |
---|---|
type |
The type of file directory to return. The type can have one of the following values:
NOTE: If you provide null or invalid values for the type, the API returns the main directory path of the primary shared or external storage. |
Example
var dirPath = kony.io.FileSystem.getExternalFilesDir(kony.io.FileSystem.DIRECTORY_PICTURES);
Return Values
String
NOTE: If the shared storage is not available, this API returns a null
value.
Exceptions
None
Platform Availability
- Android
The getExternalFilesDirs API returns the absolute paths to the application-specific directories on all the shared or external storage devices where the application can store its persistent files.
NOTE:
- From API level 29, apps do not require additional permissions to read and write files to this directory.
- The files in this directory are internal to the application, and are deleted when you uninstall the app.
Syntax
kony.io.FileSystem.getExternalFilesDirs(type);
Input Parameters
Parameters | Description |
---|---|
type |
The type of file directory to return. The type can have one of the following values:
NOTE: If you provide null or invalid values for the type, the API returns the main directory path of the primary shared or external storage. |
Example
var dirPath = kony.io.FileSystem.getExternalFilesDirs(kony.io.FileSystem.DIRECTORY_PICTURES);
Return Values
Array of Strings
NOTE: If the shared storage is not available, this API returns a null
value.
Exceptions
None
Platform Availability
- Android
NOTE: If your device runs on Android versions before Android KitKat, the kony.io.FileSystem.getExternalFilesDirs API returns the same result as the kony.io.FileSystem.getExternalFilesDir API.
The getExternalStorageDirectoryPath API returns the path to the external storage, typically sdcard.
Syntax
kony.io.FileSystem.getExternalStorageDirectoryPath()
Input Parameters
None
Example
var mainLoc = kony.io.FileSystem.getExternalStorageDirectoryPath();
Return Values
String
Exceptions
None
Platform Availability
- Android
NOTE: If the targetSdk version used is above version 28, scoped storage is enabled by default, and the legacy Storage APIs (getExternalStorageDirectoryPath) will not work. You must use scoped Storage APIs such as getExternalFilesDir and getExternalFilesDirs on devices that run on Android version 11, and above.
The getExternalStorageState API returns the current state of the shared or external storage media at the specified path.
Syntax
kony.io.FileSystem.getExternalStorageState(path);
Input Parameters
Parameters | Description |
---|---|
Path | Path to the file or directory. |
Example
var path = kony.io.FileSystem.getExternalFilesDir();
var stats = kony.io.FileSystem.getExternalStorageState(path);
Return Values
File System Constant
The File System Constant can have one of the following values:
-
kony.io.FileSystem.MEDIA_UNKNOWN
: Unknown storage state, such as when a path isn't backed by known storage media. -
kony.io.FileSystem.MEDIA_REMOVED
: Storage state if the media is not present. -
kony.io.FileSystem.MEDIA_UNMOUNTED
: Storage state if the media is present but not mounted. -
kony.io.FileSystem.MEDIA_CHECKING
: Storage state if the media is present and the disk is being checked. -
kony.io.FileSystem.MEDIA_NOFS
: Storage state if the media is present but is blank or is using an unsupported filesystem. -
kony.io.FileSystem.MEDIA_MOUNTED
: Storage state if the media is present and mounted at its mount point with read/write access. -
kony.io.FileSystem.MEDIA_MOUNTED_READ_ONLY
: Storage state if the media is present and mounted at its mount point with read/write access. -
kony.io.FileSystem.MEDIA_SHARED
: Storage state if the media is present not mounted, and shared via USB mass storage. -
kony.io.FileSystem.MEDIA_BAD_REMOVAL
: Storage state if the media was removed before it was unmounted. -
kony.io.FileSystem.MEDIA_UNMOUNTABLE
: Storage state if the media is present but cannot be mounted. Typically, this happens if the file system on the media is corrupted. -
kony.io.FileSystem.MEDIA_EJECTING
: Storage state if the media is in the process of being ejected.
Exceptions
None
Platform Availability
- Android
The getFile API returns a kony.io.File object representing the file for the given path. It returns a kony.io.File object for the specified file path. getFile API does not create a File.
Syntax
kony.io.FileSystem.getFile(string path);
Input Parameters
Parameters | Description |
---|---|
Path | path to the file or directory. |
Example
var mainLoc = kony.io.FileSystem.getDataDirectoryPath(); var myFileLoc = mainLoc + constants.FILE_PATH_SEPARATOR + "myFileToGet.txt"; var myFile = new kony.io.File(myFileLoc).createFile(); var getMyFile = kony.io.FileSystem.getFile(myFileLoc); if (getMyFile === null) { alert("getting File failed with null"); } else { alert(JSON.stringify(getMyFile.name)); }
Return Values
Kony.io.File
Platform Availability
- All native platforms
- Desktop Web
The getFileSystemStats API retrieves the detailed information about the space on a file system.
Syntax
kony.io.FileSystem.getFileSystemStats(path);
Input Parameters
Parameters | Description |
---|---|
Path | Path to the file or directory. |
Example
var path = kony.io.FileSystem.getExternalFilesDir();
var stats = kony.io.FileSystem.getFileSystemStats(path);
Return Values
A JSON Object that contains the values for the following parameters
freeBytes
: Number of bytes that are free, including reserved blocks, on the file system.
availableBytes
: Number of bytes that are free and available to applications on the file system.
totalBytes
: Total number of bytes supported by the file system.
NOTE: If the file path does not exist, this API returns a null
value.
On devices that run Android version 18 (or earlier), the value for totalBytes parameter is not returned.
Exceptions
None
Platform Availability
- Android
The getNoBackupFilesDirAPI returns the absolute path to the directory on the file system that is similar to the kony.io.FileSystem.getDataDirectoryPath API. However, the files present in the directory returned by this API are excluded during the automatic backup process to the remote storage.
Syntax
kony.io.FileSystem.getNoBackupFilesDir();
Input Parameters
None
Example
var dirPath = kony.io.FileSystem.getNoBackupFilesDir();
Return Values
String
Exceptions
None
Platform Availability
- Android
The getRawDirectoryPath API returns the application’s “raw” directory path. getRawDirectoryPath API API is applicable only on Android.
Syntax
kony.io.FileSystem.getRawDirectoryPath();
Input Parameters
None
Example
var rawDirectoryPath = kony.io.FileSystem.getRawDirectoryPath();
Return Values
Returns the directory path in the form of String.
Exceptions
None
Remarks
- In the Android platform, you should not perform read and write operations to the raw directory.
Platform Availability
- Android
- iOS
This API returns the application’s support directory path. This is only applicable for iOS.
Syntax
kony.io.FileSystem.getSupportDirectoryPath();
Input Parameters
None
Example
var supportDirectoryPath = kony.io.FileSystem.getSupportDirectoryPath();
Return Values
String
For Functional Preview, the path returned by the getSupportDirectoryPath API points to the child folder present inside the Application Support folder. This feature is available only on iOS devices.
Exceptions
None
Platform Availability
- iOS
The isExternalStorageAvailable API is used to check, if the external storage is available and accessible on the device. The isExternalStorageAvailable API returns boolean value as true/false accordingly on Android platform.
Syntax
kony.io.FileSystem.isExternalStorageAvailable();
Input Parameters
None
Example
var isExternalStorageAvialable = kony.io.FileSystem.isExternalStorageAvailable();
Return Values
Boolean
Exceptions
None
Platform Availability
- iOS
- Android
The isExternalStorageEmulated API is used to check if the primary shared or external storage media is emulated. The isExternalStorageAvailable API returns a boolean value as true/false accordingly.
Syntax
kony.io.FileSystem.isExternalStorageEmulated(File);
Input Parameters
Parameters | Description |
---|---|
File | File Object or path to the file. |
Example
var dirPath = kony.io.FileSystem.getExternalFilesDirs(kony.io.FileSystem.DIRECTORY_PICTURES); var isEmulated = kony.io.FileSystem.isExternalStorageEmulated(dirPath);
Return Values
Boolean
Exceptions
None
Platform Availability
- Android
NOTE: If this API is invoked on a device that runs on Android version KitKat, it always returns a false
value.
The isExternalStorageLegacy API is used to check if the primary shared or external storage media at the specified path is from the legacy view and includes files that are not specific to the app. The isExternalStorageLegacy API returns a boolean value as true/false accordingly.
Syntax
kony.io.FileSystem.isExternalStorageLegacy(File);
Input Parameters
Parameters | Description |
---|---|
File | File Object or path to the file. |
Example
var dirPath = kony.io.FileSystem.getExternalFilesDirs(kony.io.FileSystem.DIRECTORY_PICTURES); var isLegacy = kony.io.FileSystem.isExternalStorageLegacy(dirPath);
Return Values
Boolean
Exceptions
None
Platform Availability
- Android
NOTE: If this API is invoked on a device that runs on Android versions prior to Android Q, it always returns a true
value.
The isExternalStorageRemovable API is used to check if the primary shared or external storage media at the specified path is physically removable. The isExternalStorageRemovable API returns a boolean value as true/false accordingly.
Syntax
kony.io.FileSystem.isExternalStorageRemovable(File);
Input Parameters
Parameters | Description |
---|---|
File | File Object or path to the file. |
Example
var dirPath = kony.io.FileSystem.getExternalFilesDirs(kony.io.FileSystem.DIRECTORY_PICTURES); var isRemovable = kony.io.FileSystem.isExternalStorageRemovable(dirPath);
Return Values
Boolean
Exceptions
None
Platform Availability
- Android
NOTE: If this API is invoked on a device that runs on Android version KitKat, it always returns a false
value.
When the developer invokes this API with the list of files, the API internally iterates through the fileList and makes the network call to the URL mentioned and uploads the files. The API assumes that the application using this API has the necessary server side infrastructure to handle the upload.
Internally, the API uses AJAX-based multi-part upload of the files to the URL mentioned in all browsers except IE 8 and 9. In the case of IE 8 and 9, we provide frame-based submit as the multi-part through AJAX (as it is not handled by the browser).
NOTE: The API kony.io.FileSystem.uploadFiles cannot be tested in local jetty server included in the Quantum Visualizer. Use Tomcat to test the API. The uploadURL must have code to receive and store the files sent via Quantum Visualizer app. The sample war file UploadServlet30.war, contains code to handle uploading or storing files at server end. Both Quantum Visualizer app and UploadURL needs to be on the same domain.
Syntax
kony.io.FileSystem.uploadFiles(URL, fileList, upLoadCallBack, upLoadConfig);
Input Parameters
Parameter | Description |
---|---|
URL [String] - Mandatory | Provide target location to upload the file. |
fileList [Object] - Mandatory | Specifies the list of files to be uploaded. This is as an array of kony.io.FileSystem.file objects. |
uploadCallBack [Object] - Mandatory | The callback is invoked each time when the file is getting uploaded. The signature of the call back is expected to be as follows: uploadCallBack(URL, upLoadStates).
|
uploadConfig [Object] | Configuration parameters, which is a simple JSON object of key value pairs, that provides the possible options during the upload. Currently there are no keys. |
Example
function UploadBtn_onClick_seq0() { // Event on upload button click var uploadURL = "http://10.10.4.17:8080/fileupload/upload"; var filesQueue = [{ File object }, { File Object }]; //Array of File objects got in browseCallBack() kony.io.FileSystem.uploadFiles(uploadURL, filesQueue, upLoadCallBack); };
Limitations for File Browse and Upload APIs
- API cannot be used in pre-show, post-show, appService, pre-appinit, or post-app init.
- For details on filter types for Browse API, follow the specification provided in the IANAMediaTypes. The Quantum Visualizerdepends on the browsers respecting the given filter type and enable appropriate file selection for the end user.
- File Upload API does not work in the cross origin request scenarios. That is, the file can be uploaded only to the site from which the original app has been accessed. For more information, check CORS documentation.
- For security reasons all browsers just give name or size of the file and not parent or full path. So, file parent and full path are not available in File object in browse or upload APIs. For more information, see http://stackoverflow.com/questions/15201071/how-to-get-full-path-of-selected-file-on-change-of-input-type-file-using-jav.
- IE 8 and 9 Limitations:
- Multiple file selection will not work. As multiple attribute is not supported for input type= file, it allows the user to select only one file from the browse window even when ‘selectMultipleFiles’ is passed as true. For more information, see http://www.w3schools.com/tags/att_input_multiple.asp.
- Filters in the Browse API do not work. As accept attribute is not supported for input type= file, even through the filter is passed, it does not have any effect on browse window. User can select any file of any type. Hence, server side file validation is recommended. For more information, see http://www.w3schools.com/tags/att_input_accept.asp.
- The file object in Browse API callback method will not have file size in IE 8. IE 8 browsers do provide file path, but it is inconsistent and depends on IE 8 security configuration (IE 9 provide fakepath). We recommend to avoid accessing file parent, path and size in IE 8 and 9. File size is provided in IE 10, Firefox, and Chrome.
- IE 8 and 9 uses iframe for file upload. The uploadprogress event is not triggered and bytes uploaded information is not provided in Upload API callback. So, callback is fired only twice.
- When you submit form to iframe with FILE_UPLOAD_PROGRESS_STATE.
- When you get error or success onload event of iframe with respective state constants.
- Multiple Upload. If a widget onclick action invokes the Browse API and user selects the file multiple times from the browse window, in browse API callback, you must handle all the files (selected by the user one by one). When Upload API is called, all the files user selected is uploaded to the specified URL. If you want to upload different files on different servers or URLs, then they need to call Browse API and Upload API subsequently one after the other. That is, you need to upload the selected file before letting the user select an other file (in case user wants to upload files on different URLs).
- Empty files cannot be uploaded in case of IE browsers.
- IE 8 and 9 Limitations:
- Multiple file selection will not work. As multiple attribute is not supported for input type= file, it allows the user to select only one file from the browse window even when ‘selectMultipleFiles’ is passed as true. For more information, see http://www.w3schools.com/tags/att_input_multiple.asp.
- Filters in the Browse API do not work. As accept attribute is not supported for input type= file, even through the filter is passed, it does not have any effect on browse window. User can select any file of any type. Hence, server side file validation is recommended. For more information, see http://www.w3schools.com/tags/att_input_accept.asp.
- The file object in Browse API callback method will not have file size in IE 8. IE 8 browsers do provide file path, but it is inconsistent and depends on IE 8 security configuration (IE 9 provide fakepath). We recommend to avoid accessing file parent, path and size in IE 8 and 9. File size is provided in IE 10, Firefox, and Chrome.
- IE 8 and 9 uses iframe for file upload. The uploadprogress event is not triggered and bytes uploaded information is not provided in Upload API callback. So, callback is fired only twice.
- When you submit form to iframe with FILE_UPLOAD_PROGRESS_STATE.
- When you get error or success onload event of iframe with respective state constants.
- Multiple Upload. If a widget onclick action invokes the Browse API and user selects the file multiple times from the browse window, in browse API callback, you must handle all the files (selected by the user one by one). When Upload API is called, all the files user selected is uploaded to the specified URL. If you want to upload different files on different servers or URLs, then they need to call Browse API and Upload API subsequently one after the other. That is, you need to upload the selected file before letting the user select an other file (in case user wants to upload files on different URLs).
- Empty files cannot be uploaded in case of IE browsers.
- When the user uploads a file that has special characters in its file name, the special characters in the file name are replaced with other special characters on the server.
- Check if the user is selecting the same file again and create appropriate conditions for browseCallBack. The check will help identify same files if selected earlier and eliminate duplicate files from getting uploaded.
- Firefox Limitation. Filters with specific Mimetype might not work properly. It is a known bug in Firefox, for more information, see:
NOTE: Constants: Constants.FILE_PATH_SEPARATOR: Platform specific File path separator.
Return Values
None
Platform Availability
- Desktop Web