CGI Form Submissions
uC-HTTP-HTTPs server 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.
For more information on HTLM Forms, please refer to section Form of the HTTP Reference Guide.
Configuration
For the HTTP server
...
<form action="upload.html" ENCTYPE="multipart/form-data" method="post">to support processing of incoming form submissions, two types of configuration must be set up: the compile-time and the run-time configuration. Also, some hook functions must be defined to allow the application to retrieve the data received in the form.
Compile-time Configuration
Two compile-time configuration macros are available for the form submissions: HTTPs_CFG_FORM_EN and HTTPs_CFG_FORM_MULTIPART_EN.
The first macro, if set to DEF_ENABLED, enables the Form feature and all the functions and data associated with it. Moreover, if the multipart form must be supported the second macro should be enabled also.
See section Module Configuration for more details.
Run-time Configuration
The run-time configuration for Form submission is defined as a HTTPs_FORM_CFG structure. Your application must declare an HTTPs_FORM_CFG object and include a pointer to this object in the HTTP server instance configuration HTTPs_CFG object where the FormCfgPtr parameter is defined.
See section HTTP Form Configuration for additional details.
Hook Functions
The general HTTP Server Instance configuration structure (HTTPs_CFG) contains a pointer to an HTTPs_HOOK_CFG object. This object indexes all the hook functions required by your application.
For additional details on the configuration of hook functions, see section Hook Configuration.
To visualize when each hook function is called by the HTTP server core, see section Hook Functions.
The hook function OnReqRdySignalHook can be used to access the data received inside the form. The data is under a list of key-value pairs (parameter FormDataListPtr) inside the HTTPs_CONN object. If a lot of processing must be done with the data received, it is recommend to not do it inside the OnReqRdySignalHook hook because it will slow down all the other connection processing. Instead, the OnReqRdySignalHook hook should be used to signal another task that the data was received and is ready to be processed. In that case, the hook function OnReqRdyPollHook should be used to indicate to the server when the data processing is completed. When defined, the server will call the OnReqRdyPollHook hook until the function returns the status Ok to indicate that the processing is finished.
Usage
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 pairs transmitted.
Assuming the HTML page that look like this:
<html> <body>...
| Code Block | ||||
|---|---|---|---|---|
| ||||
<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-NameThe HTTP server core will received the POST request and save the form data inside a key-value pairs list (FormDataListPtr parameter of the HTTPs_CONN structure). The server will then call the hook function OnReqRdySignalHook (of the HTTPs_HOOK_CFG object inside the HTTPs_CFG object) to allow the application to retrieve and process the data received. The key-value pairs inside the list will be:
Key: "textbox1",
...
Value: "Text Box 1 value"
Key
...
: "textbox2",
...
Value: "Text Box 2 value"
Key
...
: "submit",
...
Value: "Submit"
section 4-12-8 “CGI Post” for further details about the implementation to this hook functionSince all connections are processing within only 1 task it is very important that all hook functions are non-blocking and can be executed quickly.
If the upper application require to takes a while to complete the data processing of CGI post , the upper application should implement a task where CGI the data can be queued and can process. The task should be polled to know if the processing is completed with the OnReqRdyPollHook hook.
Uploading files using µC/HTTP-server
It is possible to use a HTML form to upload files on the file system using µC/HTTP-server. The following listing shows an example of HTML code that can be used to implement that functionality:
| Code Block | ||||
|---|---|---|---|---|
| ||||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN">
<html>
<head>
<title>File Upload</title>
</head>
<body>
<form action="File_Upload.htm"
ENCTYPE="multipart/form-data"
method="post">
<p><b>Choose The file To Upload:</b>
<input type="file" name="file_form_field_name" ></input>
</p>
<p>
<input type="submit" name="Submit" value="Submit"></input>
</p>
</form>
</body>
</html> |
| Info |
|---|
Multipart form type must absolutely be specified in the form tag. For example: |
When the file upload feature is enabled (parameter MultipartFileUploadEn inside the run-time configuration), the µC/HTTP-server instance write the file to the default location specified by the run-time 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 OnReqRdySignalHook function is called. As example for the upper listing, the key value pair list will contains the following:
Key: "file_form_field_name", Value: "\\Path\RemoteFileName.html"
Key: "submit", Value: "Submit"
If an error occurs during the file transfer such as unable to open or write the file, the OnReqRdySignalHook function is not called, and the upper application is notified by the Error hook function.
Note that the file upload is not possible using the static file system.