uC-HTTPs supports HTML form submissions through the POST method. The following POST Internet media type are supported:
"application/x-www-form-urlencoded"is the default format for encoding key-value pairs when a web browser sends a POST request from a web form element."multipart/form-data"is the format that must be used when uploading large amount of data such as a file on a web server. It must be specified in the form tag as example:
<form action="upload.html" ENCTYPE="multipart/form-data" method="post">
When the form is posted, the web server will process the POST action and will invoke the callback with a list of key-value pair transmitted. Assuming the HTML page that look like this:
<html>
<body>
<form action="form_return_page.htm" method="post">
Text Box 1: <input type="text" name="textbox1" /><br>
Text Box 2: <input type="text" name="textbox1" /><br>
<input type="submit" name="submit" value="Submit"></input>
</form>
</body>
</html>
When the client send the request, the web server should call the callback function with the following key pair values items:
Key-Name: "textbox1", Key-Value: "Text Box 1 value"
Key-Name: "textbox2", Key-Value: "Text Box 2 value"
Key-Name: "submit", Key-Value: "Submit"
Each key pair value are stored internally to a list, when all key value pairs have been received the list is posted to the upper application using a callback function called 'GGI post' function. Since all connections are processing within only 1 task it is very important that all hook functions are non-blocking and can be executed quickly. See CGI Post for further details about the implementation to this hook function.
If the upper application takes a while to complete the processing of CGI post the upper application should implement a task where CGI data can be queued and can be polled to know if the processing is completed.
Uploading files using µC/HTTPs
It is possible to use a HTML form to upload files on the file system using µC/HTTPs. The following image shows an example of HTML code that can be used to implement that functionality:
When the file upload feature is enabled, the µC/HTTPs instance write the file to the default location specified by the configuration. If no error occurred when writing the file a key value pair will be added to the list to specify the HTML control name of the field and the absolute location of the uploaded file. Thus the upper application can easily retrieve or even move any file transmitted when the CGI Post function is called. As example for the listing in µC/HTTPs Instance Configuration, the key value pair list will contains the following:
Key-Name: "file_form_field_name", Key-Value: "\\Path\RemoteFileName.html"
Key-Name: "submit", Key-Value: "Submit"
If an error occurs during the file transfer such as unable to open or write the file, the CGI post function is not called, and the upper application is notified by the Connection Error hook function. Note that the file upload is not possible using the static file system.