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"
}
DOWNLOADING FILES WEBSOCKETS EXTENSION
When the "File Read" operation is used in a Websockets context the file data
can be retrieved as a download. This allows for the efficient transfer of
large files. This requires the generation of an ID number for the request.
It is recommended that this be a large random number that cannot be easily
guessed.
{
"Message":"File Read",
"File":"/flash/www/config/folder.png"
"RequestID":747831206503744
}
{
"Message":"File Read Response",
"File":"/flash/www/config/folder.png",
"RequestID":747831206503744,
"Status":"Ready"
}
If the Status parameter in the response indicates "Ready" the file may then
be downloaded using the following URL. This is a one-time use URL available
for a limited time.
https://[ip-address]/query.cgi?request=747831206503744
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:645]