Merge branch 'master' of https://github.com/tobychui/ArOZ-Online-System

docs/lang/dev-en-HK/4.md

@@ -112,5 +112,20 @@ The filepath paramter will provide the file location in **relative to /AOR or ab
 For type 1 and 2, you can directly load them to the user by putting the filepath in ```src``` elements.
 However, for type 3 filepaths, you will need to call to the External Disk Handler using ```./SystemAOB/functions/extDiskAccess.php?file=``` and follow by the absolute path of the file. 
 
+Here is a quick example for checking the filepath, referenced from Video module
+
+```
+if (file_exists($_GET['filepath'])|| strpos($_GET['filepath'],"extDiskAccess.php")){
+	echo '<video id="player" style="position:fixed; height:100%; max-width:100% ;top:0; left:0;" src="'.$_GET['filepath'].'" autoplay controls></video>';
+	$filename = basename($_GET['filepath'], ".mp4");
+	if (ctype_xdigit(str_replace("inith","",$filename)) && strlen(str_replace("inith","",$filename)) % 2 == 0) {
+		$decodedName = hex2bin(str_replace("inith","",$filename));
+	}else{
+		$decodedName = $filename;
+	}
+}else{
+	die('<i class="remove icon"></i>API call error: 404 File not found.');
+}
+```
 
 

docs/lang/dev-en-HK/5.md

@@ -1,3 +1,352 @@
 ["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. 
+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.
+
+<table>
+  <tr>
+    <th>Variable</th>
+    <th>Meanings</th>
+  </tr>
+  <tr>
+    <td>uid</td>
+    <td>Unique ID for this floatWindow</td>
+  </tr>
+  <tr>
+    <td>aor</td>
+    <td>ArOZ Online Root, usually ../ for WebApp moduiles</td>
+  </tr>
+  <tr>
+    <td>windowWidth</td>
+    <td>The width of the file selector window. Default 1080px</td>
+  </tr>
+  <tr>
+    <td>windowHeight</td>
+    <td>The height of the file selector window. Default 645px</td>
+  </tr>
+  <tr>
+    <td>alowMultiple</td>
+    <td>Allow selecting multiple items in the selector.</td>
+  </tr>
+  <tr>
+    <td>selectMode</td>
+    <td>Select file / folder / all. Default "file", accept {file / folder/ mix}<br></td>
+  </tr>
+  <tr>
+    <td>callBackFunctionName (floatWindow Mode Only)</td>
+    <td>Function name that expect the selector to return the result to. THIS FUNCTION NAME IS IN STRING FORMAT</td>
+  </tr>
+  <tr>
+    <td>callBack (Non floatWindow Mode Only)</td>
+    <td>Function that expect the selector to return the result to. THIS IS THE POINTER OF THE FUNCTION.</td>
+  </tr>
+</table>
+
+### 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.
+
+```
+<script src="../script/ao_module.js"></script>
+```
+
+Now, assume you want the file explorer to pop up while the user press a button. Here is an example for the process.
+
+```
+<button onClick="openFileSelector();">Select File</button>
+```
+
+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.
+
+```
+<?php
+//Assume your username is "alan"
+include_once("../SystemAOB/functions/user/userIsolation.php");
+$configs = glob(getUserDirectory() . "SystemAOB/functions/file_system/fshortcut/*.shortcut");
+var_dump($configs);
+?>
+
+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
+
+## New Item Menu
+
+