["檔案總管 API"] ![](img/devdoc/5/0.png) # 檔案總管 API ArOZ Online的檔案總管系統是整個系統的核心，因為他提供了所有WebApp模塊所需的基本功能。 簡單而言，ArOZ Online的檔案總管系統由以下元素組成 - 檔案總管 - 檔案操作 - 檔案異步同步（已編寫Go-lang，作為預編譯的二進製文件包含在內） - 檔案同步（編寫的PHP，僅兼容模式。） - 檔案選擇器 - 檔案總管的快捷選單 - 檔案的開啟方式 - 新項目列表 在本頁面將會介紹上述的功能和API。 ![](img/devdoc/5/1.png) ## 檔案總管器UI 檔案總管為ArOZ Online提供基本的文件和資料夾功能。 檔案總管UI為用戶提供了在VDI模式或PWA模式下進行操作的界面。 有關UI的更多資訊，請參閱[快速入門指南]中的進階功能。 ![](img/devdoc/5/2.png) ## 檔案操作功能 ArOZ Online由兩組檔案操作所組成。 它們提供以下檔案操作的功能 - 複製貼上 - 移動 - 壓縮和解壓縮 - UM文件名到UTF-8文件名的轉換 檔案操作中未包含以下功能。 - 重新命名 - 刪除 - 開啟方式 - 下載 ### 檔案異步功能 異步功能是一款使用go-lang編寫的程式，他可以為提供檔案異步操作。 本功能有3個主要的二進制檔案。 1. fsexec 2. fszip 3. fsconv #### fsexec 用於防止在執行檔案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). - ```icon_tag``` Icon tag is based on the ArOZ Online System Default CSS - TocasUI. See more in this [page](https://tocas-ui.com/elements/icon/). - ```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 ``` ![](img/devdoc/5/6.png) ## New Item Menu 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.