[Up]: Storage API : PutFile
Script path: /storage/bin/api/put_file.cgi
Description: Put the submitted file content into a specified file. The file wil be created if it does not exist. If the file exists, optional parameters "start" and "truncate" can be used to determine if the submitted content is to be appended to the current file or overwrite any existing content. At the end of this call, the size, owner, access rights of the file is determined by the system automatically. To put in a file description, use another API call.
INPUT (via GET or POST, but POST is recommended if "data" value is large.)
Mandatory parameters are: sid, path
Optional parameters are: data, start, truncate,
autorename, 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, or else one will be created. For new filenames, refer to [Name restriction] e.g. |
| data | =<data> Empty data value is accepted. The amount of data accepted will be all of what is contained in the "data" parameter. (There is no need to indicate end-of-file.) This data is not specifically buffered to disk during transmission except under POST with multipart/form-data encoding AND "file upload" style of submissions. In GET method of submission, the data will need to be url-encoded. Data chunk sizes recommend are 4K, 8K, 16K at a time, avoid going more than 32K at a time. And bear in mind tha url-encoding will bloat the submission size even more. This url-encoding will also happen under POST method under default ENCTYPE, that is, application/x-www-form-urlencoded. To avoid the overhead of url-encoding use POST method with multipart/form-data encoding. A multipart section showing submission of data from a <TEXTAREA> </TEXTAREA> field example is shown next. -----------------------------7d115e1fa7c "file upload" style submission will be buffered to disk during submission allowing very large data submission without hogging memory. A multipart section showing this type of submission is shown below. The "filename" and "Content-Type" information are ignored in this API, so you can fake them! -----------------------------7d115e1fa7c |
| start | = 0 .. N Default is to start at the end of file, that is, don't specify a start value in order to append to the current file. A new file will be created there if there is no existing file and start is assumed to be 0. If N is larger than the existing file content, it will be ignored, and the behavior will be to append. No error is flagged when this happens. |
| truncate | = no Default is to truncate (don't specify truncate or truncate not= 'no'). This is only meaningful when "start" is specified and points into the current existing content. The default behaviour is to truncate the existing file to the "start" point, thus removing all data after that point from the file. The new data then is laid from the starting point. If truncate=no, there is a possibility the some existing file data remains when the new data has been overlaid. Use truncate=no only if you want this behavior. |
| autorename | = yes Default for this parameter is NOT "yes", that is, do not autorename given filename. This parameter is only considered when the input filename contain illegal character. Example: My:Weird*Filename?.doc If autorename is yes, then the input filename will be renamed to have "_" in place of the illegal characters. Example: My_Weird_Filename_.doc The default is to abort and return an error condition. Characters that are not valid as filenames are \ / : * ? " > < | x00-x1F (autorename will substitute each with underscore). A filename also cannot begin with <dot> <dash> or <whitespace> (autorename will substitute the first invalid one with an underscore). Also not valid are filenames that has trailing whitespace (autorename will substitute the last whitespace with an underscore), longer than 255 characters (autorename will just take the first 255 chars). When autorename takes place, the new name used by the backend will be returned in the API (see below for details.) |
| 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> <new_file_size> <newline>
e.g.
true <TAB> 81920 <newline>
Equivalent JSON output:
{
"status" : true,
"current_size" : 81920
}
In the case of autorename, and the targeted filename has been
autorenamed, the new name is return in the second line of the response.
e.g.
true <TAB> 81920 <newline>Equivalent JSON output:
autorenamed_to <TAB> the_new_filename_.txt <newline>
{
"status" : true,
"autorenamed_to" : "the_new_filename_.txt",
"current_size" : 81920
}
Unsuccessful return:
false <tab> <error message> <newline>
e.g.
false <TAB> Disk space quota exceeded.Equivalent JSON output:
{
"http_status" : "403 Storage space quota exceeded",
"status" : false,
"errmsg" : "Disk space quota exceeded."
}