Network Component  Version 7.10.0
MDK Middleware for IPv4 and IPv6 Networking
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Common Gateway Interface (CGI)

Functions reacting on CGI requests to the HTTP server. More...

Functions

void netCGI_ProcessQuery (const char *qstr)
 Process query string received by GET request. [user-provided]. More...
 
void netCGI_ProcessData (uint8_t code, const char *data, uint32_t len)
 Process data received by POST request. [user-provided]. More...
 
uint32_t netCGI_Script (const char *env, char *buf, uint32_t buf_len, uint32_t *pcgi)
 Generate dynamic web data based on a CGI script. [user-provided]. More...
 
const char * netCGI_GetEnvVar (const char *env, char *ansi, uint32_t max_len)
 Process environment variables and convert to ANSI format. [thread-safe]. More...
 
const char * netCGI_Charset (void)
 Override default character encoding in HTML documents. [user-provided]. More...
 
const char * netCGI_ContentType (const char *file_ext)
 Add custom MIME type for unsupported file types. [user-provided]. More...
 
const char * netCGI_Redirect (const char *file_name)
 Redirect resource URL address to a new location. [user-provided]. More...
 
const char * netCGX_ContentType (void)
 Override default Content-Type for CGX script files. [user-provided]. More...
 

Description

Functions reacting on CGI requests to the HTTP server.

To process a query string that was received by a GET request, the function netCGI_ProcessQuery is used while serving a POST request is done with netCGI_ProcessData. The function netCGI_Script generates a HTML web page based on CGI scripting. Processing and conversion of environment variables is done using netCGI_GetEnvVar, while the preferred character set (language) of a browser can be retrieved with netCGI_Charset.

Function Documentation

const char * netCGI_Charset ( void  )

Override default character encoding in HTML documents. [user-provided].

Returns
pointer to user defined character set type.

The function netCGI_Charset overrides the default character encoding in a web browser. If this function is implemented and returns a non-NULL pointer, the web server adds a character encoding HTTP header. The browser then uses this information to correctly decode the character set.

If this function is not existing (or returns NULL), then the 'charset' parameter is not generated in web server's response. The browser then uses the default character encoding. This might cause troubles in displaying web pages that are encoded in different character sets. Example: an English user might not see the umlaut characters on German web pages.

Note
This function is optional.

Code Example

const char *netCGI_Charset (void) {
return ("utf-8");
}
const char * netCGI_ContentType ( const char *  file_ext)

Add custom MIME type for unsupported file types. [user-provided].

Parameters
[in]file_extfilename extension, a null-terminated string.
Returns
MIME type information:
  • pointer to user defined Content-Type.
  • NULL for unknown type.

The function netCGI_ContentType allows you to add new MIME types for the Content-Type HTML header in the response to the web service application requests. The function returns a pointer to the Content-Type HTML header. You can use this function to add new file types to the Network Component library.

The argument file_ext specifies the file extension of a requested file, which is not supported in Network Component library.

The default content type for unsupported file types is:

Content-Type: application/octet-stream\r\n

This header is used if the file type is not supported in Web server and netCGI_ContentType function does not exist in the project or if it returns a NULL pointer.

The netCGI_ContentType function is in the HTTP_Server_CGI.c module. The prototype is defined in rl_net.h.

Note
This function is optional. If missing, or returning NULL, a default content type is used for unsupported file types.

Code Example

const char *netCGI_ContentType (const char *file_ext) {
// Example
if (strcmp (file_ext, "wav") == 0) {
return ("audio/wav");
}
return (NULL);
}
const char * netCGI_GetEnvVar ( const char *  env,
char *  ansi,
uint32_t  max_len 
)

Process environment variables and convert to ANSI format. [thread-safe].

Parameters
[in]envpointer to environment variables.
[out]ansioutput buffer to write converted variable to.
[in]max_lenmaximum length of environment variable.
Returns
status information:
  • pointer to the remaining environment variables to process.
  • NULL if there are no more environment variables to process.

The function netCGI_GetEnvVar processes the string env, which contains the environment variables, and identifies where the first variable ends. The function obtains and stores the first variable and its value in the buffer pointed by ansi, in ANSI format.

The argument max_len specifies the maximum length that can be stored in the ansi buffer. If the decoded environment variable value is longer than this limit, then the function truncates it to max_len to fit it into the buffer.

Note
  • The function can process environment variables from the GET and POST methods.
  • You can call this function from the HTTP_Server_CGI.c module.
  • The web browser uses environment variables to return user-entered information that is requested in the HTTP input form.

Code Example (see netCGI_ProcessQuery)

void netCGI_ProcessData ( uint8_t  code,
const char *  data,
uint32_t  len 
)

Process data received by POST request. [user-provided].

Parameters
[in]codecallback context:
  • 0 = www-url-encoded form data.
  • 1 = filename for file upload (null-terminated string).
  • 2 = file upload raw data.
  • 3 = end of file upload (file close requested).
  • 4 = any other type of POST data (single or last stream).
  • 5 = the same as 4, but with more data to follow.
[in]datapointer to POST data.
[in]lenlength of POST data.
Returns
none.

The function netCGI_ProcessData processes the data returned from the POST method of the CGI form. The HTTP server calls this function when a user clicks the SUBMIT button of an input form.

The argument code can have the following types:

CodeData Type Meaning of *data Meaning of len
0 Form data Pointer to data string returned from the POST method Length of data string
1 Filename Pointer to a Filename for the HTTP file upload. Filename is a null-terminated string. Length of a filename
2 File data Pointer to data packet received from the host Length of data packet
3 End of fileNULL Don't care
4 Other data Pointer to data string returned from the POST method. A single packet or last packet in data stream Length of data string
5 Other data Pointer to data string returned from the POST method. The same as under 4, but with more data to follow Length of data string

The argument data point to the data that get processed.

The argument len is the data length in bytes.

Note
  • The HTTP server calls the function only if the input form (HTML source) is created with the attribute METHOD=POST. For example:
    <FORM ACTION=index.htm METHOD=POST NAME=CGI>
    ..
    </FORM>
  • Web browsers provide a filename for HTTP file upload with a path included. It is the user's responsibility to remove the path information from the filename.
  • For large files, file data is received in several small packets. The size of data packet depends on the TCP Maximum Segment Size (MSS). This value is typically 1440 bytes.
  • The XML-POST is generated from the web service application.

Code Example

The following example is available in the user code template file HTTP_Server_CGI.c. Customize it to the application's needs.

void netCGI_ProcessData (uint8_t code, const char *data, uint32_t len) {
char var[40];
switch (code) {
case 0:
// Url encoded form data received
do {
// Parse all parameters
data = netCGI_GetEnvVar (data, var, sizeof (var));
if (var[0] != 0) {
// First character is non-null, string exists
if (strcmp (var, "led0=on") == 0) {
// ... Switch LED 0 on
}
}
} while (data);
break;
case 1:
// Filename for file upload received
if (data[0] != 0) {
// Open a file for writing
file = fopen (var, "w");
}
break;
case 2:
// File content data received
if (file != NULL) {
// Write data to a file
fwrite (data, 1, len, file);
}
break;
case 3:
// File upload finished
if (file != NULL) {
// Close a file
fclose (file);
}
break;
case 4:
// Other content type data, last packet
if (strcmp (netHTTPs_GetContentType(), "text/xml; charset=utf-8") == 0) {
// Content type xml, utf-8 encoding
...
}
break;
case 5:
// Other content type data, more to follow
// ... Process data
break;
default:
// Ignore all other codes
break;
}
}
void netCGI_ProcessQuery ( const char *  qstr)

Process query string received by GET request. [user-provided].

Parameters
[in]qstrpointer to the query string.
Returns
none.

The function netCGI_ProcessQuery processes the environmental variable QUERY_STRING that is returned by the GET method of the CGI form. The HTTP server calls this function when a user clicks the SUBMIT button on the input form.

The argument qstr points to the QUERY_STRING that is returned by the GET method. The query string is terminated by a space character.

Note
The HTTP server calls the function only if the input form (HTML source) was created with attribute METHOD=GET. For example:
<FORM ACTION=index.htm METHOD=GET NAME=CGI>
..
</FORM>

Code Example

The following example is available in the user code template file HTTP_Server_CGI.c. Customize it to the application's needs.

void netCGI_ProcessQuery (const char *qstr) {
char var[40];
do {
// Loop through all the parameters
qstr = netCGI_GetEnvVar (qstr, var, sizeof (var));
// Check return string, 'qstr' now points to the next parameter
if (var[0] != 0) {
// First character is non-null, string exists
// Example of a parameter "ip=fe80::1c30:6cff:fea2:455e"
if (strncmp (var, "ip=", 3) == 0) {
uint8_t ip_addr[NET_ADDR_IP6_LEN];
// Read parameter IP address submitted by the browser
netIP_aton (&var[3], NET_ADDR_IP6, ip_addr);
...
}
}
} while (qstr);
}
const char * netCGI_Redirect ( const char *  file_name)

Redirect resource URL address to a new location. [user-provided].

Parameters
[in]file_nameresource filename, a null-terminated string.
Returns
URL redirection information:
  • pointer to user defined Location.
  • NULL for no URL address redirection.

The function netCGI_Redirect allows you to redirect URL address of a missing resource to a new location. The function returns a pointer to the Location HTML header. Web server calls this function, if the requested resource is not found on the server.

When netCGI_Redirect function returns valid URL location, Web server returns 301 Moved Permanently error code with HTML header containing a new location in the response to the web service application request.

The argument file_name specifies the full path name of a requested resource.

The netCGI_ContentType function is in the HTTP_Server_CGI.c module. The prototype is defined in rl_net.h.

Note
This function is optional. If missing, or returning NULL, server returns 404 Not Found to the client on file not found error.

Code Example

const char *netCGI_Redirect (const char *file_name) {
if (strcmp (file_name, "lxi/identification") == 0) {
return ("/lxi_identification.cgx");
}
return (NULL);
}
uint32_t netCGI_Script ( const char *  env,
char *  buf,
uint32_t  buf_len,
uint32_t *  pcgi 
)

Generate dynamic web data based on a CGI script. [user-provided].

Parameters
[in]envenvironment string.
[out]bufoutput data buffer.
[in]buf_lensize of output buffer (from 536 to 1440 bytes).
[in,out]pcgipointer to a session's local buffer of 4 bytes.
  • 1st call = cleared to 0.
  • 2nd call = not altered by the system.
  • 3rd call = not altered by the system, etc.
Returns
number of bytes written to output buffer.
  • return len | (1U<<31) = repeat flag, the system calls this function again for the same script line.
  • return len | (1U<<30) = force transmit flag, the system transmits current packet immediately.

The function netCGI_Script is what the script interpreter calls when interpreting the script to output the dynamic part of the HTTP response. The script interpreter calls netCGI_Script for each line in the script that begins with the command c. You must customize the netCGI_Script function so that it can understand and use the input string from the script.

The argument env is a pointer to the input string to create the dynamic response. It is the same string of bytes that is specified in the CGI script code using the c command.

The argument buf is a pointer to the output buffer where the netCGI_Script function must write the HTTP response.

The argument buf_len specifies the length of the output buffer in bytes.

The argument pcgi is a pointer to a variable that never gets altered by the HTTP Server. Hence, you can use it to store parameters for successive calls of the netCGI_Script function. You might use this to store:

  • loop counters
  • number of sent bytes
  • pointer to a local status buffer.
Note
  • The contents written into the output buffer by the netCGI_Script function must be HTML code.
  • c is a command that is available in the scripting language of the Network Component.
  • The length of the output buffer (buf_len) might vary, because the length is determined by the TCP socket Maximum Segment Size (MSS) negotiation. The buffer length is normally around 1400 bytes for local LAN. But this can be reduced to 500 bytes or less. It also varies because the HTTP Server tries to optimize the number of generated TCP packets. It calls this function again to use the complete available buffer. It stops when there are only 240 or less bytes free in the buffer. This causes the packet to be generated and transmitted. If you want to force the HTTP Server to transmit the packet, you need to or the return value from this function with 1U<<30.
  • If netCGI_Script writes more bytes than buf_len into the output buffer, a system crash from a corruption of the memory link pointers is highly likely.
  • The input string env might contain single-character subcommands to tell the netCGI_Script function how to process the script line correctly. There are no rules for these subcommands, so you can create and use your own commands.
  • The argument pcgi is private to each HTTP Session. The HTTP Server clears the data in the pcgi pointer to 0, before netCGI_Script is called for the first time in each session.
  • netCGI_Script must update the contents in pcgi for each call. You can use the 4 bytes in pcgi to store data in any format.

Code Example

The following example is available in the user code template file HTTP_Server_CGI.c. Customize it to the application's needs.

uint32_t netCGI_Script (const char *env, char *buf, uint32_t buf_len, uint32_t *pcgi) {
uint32_t len = 0;
// Analyze a 'c' script line starting position 2
// c a i <td><input type=text name=ip value="%s" size=40 maxlength=40></td>
char ip_ascii[40];
switch (env[0]) {
case 'a' :
switch (env[2]) {
case 'i':
// Write the local IP address
netIP_ntoa (NET_ADDR_IP6, IpAddr, ip_ascii, sizeof(ip_ascii));
len = sprintf (buf, &env[4], ip_ascii);
break;
..
}
break;
}
return (len);
}
const char * netCGX_ContentType ( void  )

Override default Content-Type for CGX script files. [user-provided].

Returns
pointer to user defined Content-Type.

The function netCGX_ContentType allows you to change the Content-Type HTML header in the response to the web service application requests. The function returns a pointer to the new Content-Type HTML header. You can use this function to override the default content type header from the Network Component library. This content type header is used in cgx script responses.

The default content type header in cgx script response is:

Content-Type: text/xml\r\n

This header is used if the netCGX_ContentType function does not exist in the project or if it returns a NULL pointer.

The netCGX_ContentType function is in the HTTP_Server_CGI.c module. The prototype is defined in rl_net.h.

Note
This function is optional. If missing, or returning NULL, a default "text/xml" content type is used.

Code Example

const char *netCGX_ContentType (void) {
return ("text/xml; charset=utf-8");
}