["File System API"] ![](img/devdoc/5/0.png) # File System API ArOZ Online File System is the core of the whole cloud software system as it provide all the fundemental functions that is required for all WebApp modules. In simple words, the file system of ArOZ Online System consists of the following elements - File Explorer - File Operation Function Group - File System Asynchronize Function Group (Go-lang written, included as a pre-compiled binary file) - File System Synchronize Function Group (PHP written, compatibility mode only.) - File Selector - File Explorer Shortcuts - File Extension Default Opener - New Item Menu In this page, the functions and the API of the elements above will be introduced. ![](img/devdoc/5/1.png) ## File Explorer UI The File Explorer provide basic file and folder navigation functions for the ArOZ Online System. The File Explorer UI provides the interface for users to interact with on VDI Mode or PWA Mode. See Advanced Documentation in Quick Start Guide for more information of the UI. ![](img/devdoc/5/2.png) ## File Operation Function Group The ArOZ Online System consists of two set of file operation function groups. They provide interface for performing the following file operations - Copy & Paste - Move - Compress & Decompress - UM-Filename to UTF-8 Filename Conversion The following functions are not included in the file operation function groups. - Rename - Delete - Open / Open With - Download ### File System Asynchronize Function Group The Asynchronize function group is a set of go-lang written programs that provide asynchronize file operation functions to the File Explorer. In the momenet of this document been written, there are 3 main binary files. 1. fsexec 2. fszip 3. fsconv #### fsexec ArOZ Online System File Explorer - Freeze Script Execution Application, design for replacing those script that was freezing the system while file IO. ##### What is fsexec Freeze Script Execution Application - Short for fsexec, is a binary written in golang to replace the old scripts in the ArOZ Online File System that would freeze the whole PHP server during file IO operations. This script make use of golang's super fast IO and processing ability and make file operation much faster on the new implementation. The fsexec application will receive the command as two parts. In most case, you will be using these funcitons only. ./fsexec {uuid} {command} where command is a string in base64 encoded JSON string. ##### How to use fsexec For example, you want to use the funciton [copy] with paramter {source} and {target}. First, you need to convert the command into an array and parse it as JSON string. For example, you have the following command array: ``` ["copy","./test.txt","target/test.txt"] ``` Next, you would want to stringify it as JSON string. ``` "[\"copy\",\"./test.txt\",\"target/test.txt\"]" ``` Then, you can convert the string above into base64 representation. This is what you will get: ``` WyJjb3B5IiwiLi90ZXN0LnR4dCIsInRhcmdldC90ZXN0LnR4dCJd ``` Lastly, you call the fsexec with the following command. Assumeing the {uuid} is [123] ``` ./fsexec 123 WyJjb3B5IiwiLi90ZXN0LnR4dCIsInRhcmdldC90ZXN0LnR4dCJd ``` Here are some examples: ``` # copy test.txt test/test.txt ./fsexec uuid_string WyJjb3B5IiwidGVzdC50eHQiLCJmb2xkZXIvdGVzdC50eHQiXQ== # copy_folder test/ target/test/ ./fsexec uuid_string WyJjb3B5X2ZvbGRlciIsInRlc3QvIiwidGFyZ2V0L3Rlc3QvIl0= ``` #### fszip ArOZ Online System File Explorer - File System Zipping Backgroundworker, design to replace the legacy zipping PHP script. ##### What is fszip File System Zipping Backgroundworker - Short for fszip, is a backgound working script that is design to replace the current PHP based zipping method used by the file explorer. This work similar to fsexec with asynchonized design to prevent the main PHP server from freezing due to the zipping process. This is particularly useful on low power host like the Raspberry Pi Zero series. ##### How to use fszip Although we strongly recommend using the fszip via file explorer API, you can call the binary directly with the following command. ``` ./fsexec {uuid} {command_in_base64_encoded_JSON_string} ``` The command has to be in one of the format that fits the following rule ``` // Command Structure: // [{"zip" / "unzip", "{source}", "{target}"] //Examples //["zip","test","test.zip"] //Zip the folder "test" into "test.zip" ./fszip uuid1 WyJ6aXAiLCJ0ZXN0IiwidGVzdC56aXAiXQo= //["unzip","test.zip","unzip"] //Unzip the folder "test.zip" to unzip/ ./fszip uuid2 WyJ1bnppcCIsInRlc3QuemlwIiwidW56aXAiXQo= ``` #### fsconv ArOZ Online File System File Naming Method Converter - fsconv, design to do quick conversion between UM-filename and UTF8 filename on local file system. ##### What is fsconv fscov is a core library for converting Upload Manager File Naming Method that is commonly used in ArOZ Online System to UTF-8 filename that works on standard Windows + NTFS environment. This is a standalone implementation other than the original one which use Javascript in ao_module or even the older one PHP based conversion script. ##### How to use fsconv fsconv support the following methods. ``` Usage of fsconv.exe: -i string Input filename. -r Enable recursive filename translation. -rd Recursive rename directory only. -rf Recursive rename file only. -um Convert to UMfilename format -utf Convert to standard UTF-8 filename format ``` Here are some example commands ``` #Convert all files, directories and their subdirs into UTF8 filename ./fsconv -r -utf -i test/ #Convert all files, directories and their subdirs into umfilenames ./fsconv -r -um -i test/ #Convert all files and files in subdirs into umfilenames but leave out foldername. ./fsconv -rd -um -i test/ #Convert all directories and subdirs into umfilenames but leave out filenames. ./fsconv -rf -um -i test/ ``` To perform quick translations, you can also call the application with following shortcuts ``` #Convert all files in current and subdirs into UTF-8 (or local encoding) filenames ./fsconv #Convert all files in current and subdirs into um-filenames ./fsconv -um ``` #### Process States Log for fsexec and fszip The fsexec and fszip application will create a folder named "log" if it doesn't exists. Inside the log folder, you would found "done" and "error" sub-folders. In simple words: - For all successfully finished file operation, its log will be stored in "done" directory. - For all failed file operation, its log will be stored in "error" directory. - For all processing file operation, its log will be stored under "log/" directory but not its subfolders. ### File System Synchronize Function Group The Synchronize function group is a set of php scripts written since the early stage of beta phrase. They provide compatibility over the system if the backstage doesn't support binary execution / permission required is not met. **It is not recommended to use this set of function group as they will freeze the PHP server while performing the file operation. Only use them if you have encountered compatibility issues with the go-lang compiled binary files** The following is a list of functions and its intake parameter. For each paramter that require paths, *feed in relative path from the script itself or absolute path* instead of the path of your WebApp script. ``` //Copy File from source to target copy.php?from={source_path}&target={target_path} //Copy Folder from source to target copy_folder.php?from={source_path}&target={target_path} //Zip folder to file_system/export/ directory zipFolder.php?folder={source_path} //Or with defined foldername included in the zip filename zipFolder.php?folder={source_path}&foldername={foldername_in_utf8} //Move file or folder from source to target (Or rename) move.php?from={source_path}&to={target_path} ``` ![](img/devdoc/5/3.png) ## File Selector ArOZ Online File System provide a simple way to access the file list and allow users to select files within the file system of your host device - The File Selector. The file selector API can be called via the following two commands ``` //Under VDI Mode, popup as a new floatWindow ao_module_openFileSelector(uid,callBackFunctionName, windowWidth = 1080, windowHeight = 645, allowMultiple = false, selectMode = "file") //Under Normal Mode, popup as a new tab window (Require localStorage) ao_module_openFileSelectorTab(uid, aor,allowMultiple = false, selectMode = "file",callBack=console.log ``` Here is a table showing the different meaning of each parameters.
Variable Meanings
uid Unique ID for this floatWindow
aor ArOZ Online Root, usually ../ for WebApp moduiles
windowWidth The width of the file selector window. Default 1080px
windowHeight The height of the file selector window. Default 645px
alowMultiple Allow selecting multiple items in the selector.
selectMode Select file / folder / all. Default "file", accept {file / folder/ mix}
callBackFunctionName (floatWindow Mode Only) Function name that expect the selector to return the result to. THIS FUNCTION NAME IS IN STRING FORMAT
callBack (Non floatWindow Mode Only) Function that expect the selector to return the result to. THIS IS THE POINTER OF THE FUNCTION.
### Example Codes To start the file selector, you need to first include the ao_module into your WebApp module with the following code in the head section of your HTML / PHP file. ``` ``` Now, assume you want the file explorer to pop up while the user press a button. Here is an example for the process. ``` ``` As you need to use different file selector mode in or out of VDI mode, here is an example script to open file selector in different mode with VDI checking. ``` if (ao_module_virtualDesktop){ var uid = ao_module_utils.getRandomUID(); ao_module_openFileSelector(uid,"addFileFromSelector",undefined,undefined,true); }else{ var uid = ao_module_utils.getRandomUID(); ao_module_openFileSelectorTab(uid,"../",true,"file",addFileFromSelector); } ``` The returned file selector results will be an array in JSON format. Here is an example of the code which can catch the returned results. ``` function addFileFromSelector(fileData){ result = JSON.parse(fileData); for (var i=0; i < result.length; i++){ var filename = result[i].filename; var filepath = result[i].filepath; //DO SOMETHING HERE } } ``` ![](img/devdoc/5/4.png) ## File Explorer Shortcuts The file explorer shortcuts is a set of ```.shortcut``` files located under user profile directory. The .shortcut files contains the following information, each data is seperated by a newline. (\n or \r\n depends on your host device operating system). ``` foldershrct {Name of the shortcut} {Path of the shortcut relative to /AOR} {icon of the shortcut, reference from system default css} ``` For example, here is a shortcut for the Audio module's uploads directory which points to ```Audio/uploads``` and with a music icon. ``` foldershrct Musics Audio/uploads music icon ``` To modify the default shortcuts, your WebApp can add files into the ```file_system/fshortcut``` directory. If your WebApp needs to add shortcuts to the file explorer for a particular user, you might need to access the local user configuration folder which is usually under ```/etc/AOB/users/{username}/SystemAOB/functions/file_system/fshortcut/*.shorcut```. To get the full path of the user configuration directory, we recommend using the functions inside ```functions/users/userIsolation.php``` instead. ``` Returned value C:\wamp\www\private\AOB\YourWebApp\index.php:5: array (size=4) 0 => string '/etc/AOB/users/alan/SystemAOB/functions/file_system/fshortcut/1555308037.shortcut' (length=77) 1 => string '/etc/AOB/users/alan/SystemAOB/functions/file_system/fshortcut/1555308041.shortcut' (length=77) 2 => string '/etc/AOB/users/alan/SystemAOB/functions/file_system/fshortcut/1557888190.shortcut' (length=77) 3 => string '/etc/AOB/users/alan/SystemAOB/functions/file_system/fshortcut/1557888194.shortcut' (length=77) ``` ## File Extension Default Opener File Explorer can be used as the middle-ware to open any files in the ArOZ File System. However, you can only open files from /AOR or /media. In the following section, the method on how to call the API and how to set default opening module will be introduced. ### File Opening API File Explorer provide API for opening a new file with given file opening module. To open a file from anyother module, you will need to request the File Explorer File Opening API with the following paramters. Example with ao_module wrapper ``` //Example for opening a file on Desktop named "file.mp4": ao_module_openFile("Desktop/files/username/file.mp4","file.mp4"); //You can also define a different name for the opener. Here is an example: ao_module_openFile("Desktop/files/TC/inithe38090e5b08fe9878ee5b48ee4babae38091546f75686f754d4144202d20546f75686f752026204e69746f72692047657420446f776e2120282b6c797269632920e380904844e38091205b373230705d.mp4","【小野崎人】TouhouMAD - Touhou %26 Nitori Get Down! (+lyric) 【HD】 [720p].mp4"); ``` Example for direct calling to File Explorer API (Not recommended) ``` SystemAOB/functions/file_system/index.php?controlLv=2&mode=file&dir={filepath}&filename={filename} ``` ### Adding / Changing default opener WebApp Your WebApp can modify the default opener by editing the respetive config file. In most case, the default openers defination should be stored under ```/file_system/default/*.csv```. The format inside the default opener definations are as follows. ``` module_directory,open_mode,icon_tag,window_width,window_height,allow_resize(0/1),glass_Effect_mode(0/1) ``` - ```Module directory``` The directory that your put your WebApp into relative to AOR. - ```open_mode``` The opening mode of your module. Supports ```default / floatwindow / embedded``` - ```default``` Open the file with default application, filename pass by variable "filename" - ```floatwindow``` Open the file with floatWindow if it is under VDI mode. If not, redirect to the application page. - ```embedded``` Open the file with embedded mode if it is under VDI mode.(Make sure you have the embedded.php under the module root folder). - ```window_width``` Windows default width in pixel - ```window_height``` Windows default height in pixel - ```allow_resize``` Allow window to be resized. Override in non-VDI mode. - ```glass_Effect_mode``` Launch window with no background color. Override in non-VDI mode. ![](img/devdoc/5/5.png) Here is an example from the png file extension default opener defination file. ``` Photo,embedded,file image outline,720,480,1,0 ``` ## New Item Menu ![](img/devdoc/5/6.png) The New Item Menu provide functions for users to create new file inside the file explorer in the current directory that they are browsing. Developers can add any new file to the list by putting a template inside ```file_system/newitem```. All files added will be available to all users.