GetFile

Script path: /storage/bin/api/get_file.cgi

Description: Returns the content of the specified file, either in its entirety or in part, by specifying a starting point (offset) and the amount to get.

INPUT (via GET or POST)

Mandatory parameters are: sid, path
Optional parameters are: start, length, ofmt

sid	session id of the login user. [mandatory]
path	path to a file [mandatory] Please refer to [How to specify a path]. path must point to an existing file. e.g. path=/Private/MyFile.avi - get content of file MyFile.avi in "Private" area
start	= 0 .. N The point to begin extracting the file content. Default is start=0 (when start is unspecified), that is, begin from the first byte. If N is larger than the file content, no data is returned, and no error is flagged either.
length	= 0 .. M The number of bytes to extract from the start point. To extract all remaining content from the starting point, just don't specify any value for length. So, to get the entire file content, just leave out start and length. This will get you everything from starting point (first byte) until the end of file. Specifying length=0 is dumb but accepted. If M is more than what is actually available to return, the amount of data returned is less than M. This is not an error, so check the returned data to see the amount of file content extracted. Usually this value is the same as input M, but if it is less, then you could have hit the end of file.
cl	= 1 or 'y' The cl parameter tell the API to insert the appropraite Content-Length header in case of successful return. The default behaviour is that the API does NOT insert Content-Length header and leaves it to the webserver (e.g. Apache) to do it if it deems so or even chunked or gzip encode the content before responding back. (In my tests, the use of cl=1 does not prevent Apache from returning a chunked version of the original output.)
pure_data	= 1 or 'y' This optional parameter is to tell the API to NOT include the legacy first line of string ( "true [data-length]" ) that is inserted before the file content follows. The HTTP Status and Content-Length headers will represent this legacy information instead. Please inspect HTTP Status to determine if the API has returned successfully or not. A "200 OK" status will mean a successful return.
ofmt	= null \| json \| jsonp null is the default, and the legacy "flat" output format is returned. json means the output format is in JSON format jsonp is like json, but in "pretty" form for easier human readability.

OUTPUT (content-type: text/plain)

Successful return:

true <tab> <number_of_bytes_actually_retrieved> <newline>
<the_extracted_file_content_(if_any)_will__here>
:

e.g.

true <TAB> 0

true <TAB> 68
heuhfmsbjcbksbbshbabknzknsknbabibjwj
asdffhn83lwhf92jir492o039jr093u

     NOTE: There is NO JSON formatted output upon successful return. After the first output line, the rest of the content is the file data requested.

     NOTE: If pure_data parameter is enabled, the first line "true <TAB> NN" will NOT be present.
     Please inspect HTTP Status to determine if the API has returned successfully or not. A "200 OK" status will mean a successful return.

Unsuccessful return:

      false <tab> <error message> <newline>

e.g.

      false <TAB> Cannot open file for read.

Equivalent JSON output would look like the following:

      {
       "http_status" : "500 Cannot open file for read",
       "status" : false,
       "errmsg" : "Cannot open file for read."
      }

In both legacy "flat" output and also JSON output, appropriate HTTP header status codes are also returned e.g. 200 OK, 401 Invalid user profile, etc.