Form

Owned by Former user (Deleted)
Last updated: Mar 02, 2015 by Former user (Deleted)
4 min read

uC-HTTP-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 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 pairs transmitted.

Assuming the HTML page that look like this:

HTML Page Example Application Form
 <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>

The 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"

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.

If the upper application takes a while to complete the data processing, the upper application should implement a task where the data can be 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:

HTML Page Example Multipart Form
<!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>

Multipart form type must absolutely be specified in the form tag. For example: <form action="upload.html" ENCTYPE="multipart/form-data" method="post">

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.