JANOS Help System: [Commands] [Topics] [Tech Support] [Printable Manual] [Search]
JMP Protocol FILE SYSTEM COMMANDS The JNIOR supports a file system comparable to that on the PC. It is not possible to support, maintain or program a JNIOR without access to the file system. The JMP Server provides access to files for reading and writing depending on login permissions. This then provides for the greatest flexibility in application development. FILE LIST REQUEST The "File List" message is used to request a listing of files in a particular directory/folder within the file system. This solicits a "File List Response" message providing the content. The response echoes the requested "folder" specification and supplies the "Content" as an array of objects each specifying the "Name", "Size", and last modification timestamp "Mod" for the file or folder. Note that a folder is distinguished from a file by the inclusion of a trailing '/' in the name. The folder's size is a count of the items it contains. A trailing '/' is not necessary in the folder specification. A typical exchange follows. The response message can be quite extensive depending on the number of files your system stores. TRANSMITTED RECEIVED { "Message":"File List", "Folder":"/" } { "Message":"File List Response", "Folder":"/", "Content":[ { "Name":"etc/", "Size":1, "Mod":"07 Jul 2016 10:25" }, { "Name":"temp/", "Size":0, "Mod":"14 Sep 2016 13:16" }, { "Name":"flash/", "Size":38, "Mod":"23 Sep 2016 07:50" }, { "Name":"manifest.json", "Size":32698, "Mod":"29 Jul 2016 10:26" }, { "Name":"jniorsys.log.bak", "Size":65557, "Mod":"20 Sep 2016 15:49" }, { "Name":"jniorsys.log", "Size":16526, "Mod":"23 Sep 2016 07:52" }, { "Name":"jniorboot.log.bak", "Size":1056, "Mod":"23 Sep 2016 07:33" }, { "Name":"jniorboot.log", "Size":1010, "Mod":"23 Sep 2016 07:50" } ] } FILE READ REQUEST The "File Read" operation is used to obtain the data for a single file. Data is returned using Base64 encoding. This allows for the transfer of files containing binary data. The "Encoding" parameter indicates "base64". At this time this is the only encoding that is supported. The "Size" parameter indicates the size of the file and the length of the decoded content of the "Data" parameter. TRANSMITTED RECEIVED { "Message":"File Read", "File":"/flash/www/config/folder.png" } { "Message":"File Read Response", "File":"/flash/www/config/folder.png" "Size":329, "Encoding":"base64", "Data":"iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAA... UQBG+9eyXUtY0pRt27bXtsaWXGtYss2L533Xej... NEN3vhsJvBA4DS7r5GwgK9bjkyDG7DmNWoxSyw... RuNikAzjk6AWQvVxDk5KcFEN0QjZAtUG3Q6zh9... 1bhsgLhZhDQjGZIvhUVvuRqhd5NxxEXKcVHHx+... ", "Status":"Succeed" } READING LARGE FILES For very large files the "File Read Response" can become quite huge. This can lead to memory and performance concerns. Fortunately you can optionally use "Limit" and "Offset" parameters to read sections of the file while limiting the "data" content size. Repeated "File Read" requests can then be used to retrieve the entire file. This is also useful if the application requires the retrieval of only a small amount of information from a certain offset in a file and not the entire file. When an "Offset" is specified in the "File Read" request the content of "Data" reflects the bytes starting at the file offset. A value of "0" indicates the beginning of the file. When the "Limit" parameter is specified, the read operation will return only that number of bytes or the balance of the file whichever is less. When either "Limit" or "Offset" are specified the "File Read Response" will contain a "NumRead" parameter indicating the actual number of bytes read. The "Size" parameter will always reflect the total file size. The following is an example of a the exchanges needed to read a file limiting the message size. Note that you might likely be able to transfer files as large as 128KB in a single message. TRANSMITTED RECEIVED { "Message":"File Read", "File":"/flash/www/config/folder.png" "Limit":256, } { "Message":"File Read Response", "File":"/flash/www/config/folder.png", "Size":329, "Offset":0, "Limit":256, "NumRead":256, "Encoding":"base64", "Data":"iVBORw0KGgoAAAANSUhEUgAAABAAAA... GUQBG+9eyXUtY0pRt27bXtsaWXGtYs... VANEN3vhsJvBA4DS7r5GwgK9bjkyDG... MxeRuNikAzjk6AWQvVxDk5KcFEN0Qj... ", "Status":"Succeed" } { "Message":"File Read", "File":"/flash/www/config/folder.png" "Offset":256, "Limit":256, } { "Message":"File Read Response", "File":"/flash/www/config/folder.png", "Size":329, "Offset":256, "Limit":256, "NumRead":73, "Encoding":"base64", "Data":"M0YfZOC0BOfVuGyAuFmENCMZki+FRW... ", "Status":"Succeed" } FILE WRITE REQUEST The "File Write" operation is used to transfer a file to the JNIOR. The write request specifies the target "File" from the root of the file system. The "File" parameter must be present for the request to be considered valid. Since files may contain binary data the "Data" portion of the message is encoded with Base64 encoding. The "Encoding" parameter must be specified as precisely as "base64". The "Size" parameter is required and must define the intended size of the file in bytes. It must match the decoded Base64 "Data" content in length. The data is decoded and the byte count compared to that specified before attempting to write the file. You may optionally specify the last modification timestamp parameter "Mod" for the file. The timestamp is represented as a Linux time in milliseconds since midnight January 1st 1970 in Universal Coordinated Time (UTC). If present the last modification time for the resulting file will be as specified. Once the file is written the "File Write Response" is returned. The "File" and "Size" are reflected in the response (as would any "Meta"). The formatted timestamp is also returned in a "Mod" parameter. The "NumWritten" parameter reflects the result of the file write. This should match the specified "Size" value if the write is to be successful. A value less than zero indicates an error. A typical exchange follows. TRANSMITTED RECEIVED { "Message":"File Write", "File":"/temp/main.c", "Size":144, "Mod":1310414726000, "Encoding":"base64", "Data":"DQojaW5jbHVkZSAiaW80MzAuaCINCg0KaW50IG1haW4oIHZvaWQgKQ0Kew0KIC... bWVyIHRvIHByZXZlbnQgdGltZSBvdXQgcmVzZXQNCiAgV0RUQ1RMID0gV0RUUF... dHVybiAwOw0KfQ0K" } { "Message":"File Write Response", "File":"/temp/main.c", "Size":144, "Mod":"11 Jul 2011 16:05", "NumWritten":144, "Status":"Succeed" } WRITING LARGE FILES For very large files the "File Write" message can become huge. This can lead to memory and performance concerns. Fortunately, you can optionally use the boolean parameter "Append" to break file writes into manageable blocks. To append to an existing file you use the "File Write" message exactly as described above. You must include an additional parameter named "Append" set to the value of "true". In this case the file must previously exist and the data included with the "Data" parameter will be appended to it. The write operation will fail if the file is not present. So to transfer a large file using multiple messages the first must not indicate "Append". It would be included only in subsequent "File Write" messages. This will insure that the resulting file will be as you are expecting. In this case the returned "Size" parameter will increase as the size of the target file increases by the "NumWritten" byte count. FILE REMOVE REQUEST One or more files or folders can be removed/deleted using the "File Remove" request. The "Files" parameter is an array of file/folder names. You do not use a trailing '/' when specifying a folder in this request. The JNIOR will attempt to remove each file/folder specified in the array. Each individual deletion may or may not succeed. The "File Remove Response" will enumerate the successful deletions in a "Succeed" array. Similarly any failures will be listed in a "Fail" array. Depending on the results the response message may contain either a "Succeed" array or a "Fail" array or both. Between the two arrays the results of each attempt for those items listed in the original "Files" array will be reported. For example: TRANSMITTED RECEIVED { "Message":"File Remove", "Files":[ "/flash/image.txt", "/flash/main.c" ] } { "Message":"File Remove Response", "Succeed":[ "/flash/image.txt", "/flash/main.c" ] } Here we attempt to remove a folder and the request fails. In this case we expect that it would fail both because the folder contains files and sub-folders (it is not empty) and also because it is a special system folder. You cannot remove the /etc, /flash, or /temp folders. You also cannot remove any content from the /etc folder. TRANSMITTED RECEIVED { "Message":"File Remove", "Files":[ "/flash" ] } { "Message":"File Remove Response", "Fail":[ "/flash" ] } FILE RENAME REQUEST You may rename a file or folder using the "File Rename" request. In this case you specify the file/folder with the "old" parameter and the new file/folder name with the "New" parameter. The files must be specified from the root of the file system and both specifications must be in the same folder. You cannot "move" a file through a rename operation. A file/folder matching the "New" specification cannot already exist. The "File Rename Response" reiterates the request and adds a "Result" parameter. The "Result" will be either "Succeed" or "Fail" reflecting the result of the rename operation. An example follows. TRANSMITTED RECEIVED { "Message":"File Rename", "Old":"/flash/main.c", "New":"/flash/test-prog.c" } { "Message":"File Rename Response", "Old":"/flash/main.c", "New":"/flash/test-prog.c", "Result":"Succeed" } FILE MKDIR REQUEST The ability to create a folder completes the set of file system functions. Here you can create a new folder using the "File Mkdir" message. The new folder is specified from the root of the file system by the "Folder" parameter. The "File Mkdir Response" reiterates the "Folder" and adds a "Result" which will be either "Succeed" or "Fail" depending on the outcome of the creation attempt. TRANSMITTED RECEIVED { "Message":"File Mkdir", "Folder":"/flash/testing" } { "Message":"File Mkdir Response", "Folder":"/flash/testing", "Result":"Succeed" } [/flash/manpages/protocol.hlp:668]