HTTP Web Server

HTTP Web Server routines are used to run and configure services of the built-in web server. More...

Functions
uint8_t	http_check_account (const char *username, const char *password)
	Check if an user account exist in the user database.
uint8_t	http_get_user_id (void)
	Retrieve the user identification.
bool	http_accept_client (const uint8_t *ip_addr, uint16_t port)
	Accept or deny connection from remote HTTP client.
bool	http_file_access (uint8_t user_id, const char *fname)
	Check if remote user is allowed to access a file on HTTP server.
char *	http_server_fgets (void *file, char *buf, uint32_t size)
	Read a string from a file in HTTP server.
void	http_server_fclose (void *file)
	Close a file previously open in HTTP server.
void *	http_server_fopen (const char *fname)
	Open a file for reading in HTTP server.
uint32_t	http_server_fread (void *file, uint8_t *buf, uint32_t len)
	Read block of data from a file in HTTP server.
uint32_t	http_server_ftime (const char *fname)
	Retrieve last modification time of a file.
uint32_t	http_utc_time (uint8_t hr, uint8_t min, uint8_t sec, uint8_t day, uint8_t mon, uint16_t year)
	Convert generic time to UTC time format.
const char *	http_get_env_var (const char *env, char *ansi, uint32_t maxlen)
	Process environment variables and convert to ANSI format.
const char *	http_server_get_content_type (void)
	Get Content-Type HTML header, received in XML post request.
const char *	http_server_get_lang (void)
	Retrieve the preferred language setting from the browser.
int32_t	http_server_get_session (void)
	Get current session number of HTTP server.
netStatus	http_server_get_client (uint8_t *ip_addr, uint8_t *mac_addr)
	Get IP and MAC address of connected remote machine.
void	cgi_process_data (uint8_t code, const char *data, uint32_t len)
	Process data received by POST request.
void	cgi_process_query (const char *qstr)
	Process query string received by GET request.
uint32_t	cgi_script (const char *env, char *buf, uint32_t buflen, uint32_t *pcgi)
	Generate dynamic web data from a script line.
const char *	cgi_content_type (const char *file_ext)
	Add custom MIME type for unsupported file types.
const char *	cgx_content_type (void)
	Override default Content-Type for CGX script files.
const char *	http_encoding (void)
	Override default character encoding in html documents.

Description

HTTP Web Server routines are used to run and configure services of the built-in web server.

A web server is used to host websites and to deliver the web pages to clients using the Hypertext Transfer Protocol. There are two types of web pages which are stored on a web server and sent to a web client on request:

• Static Web pages do not change their content. When the page is requested, it is sent to the web client as it is. It is not modified.
• Dynamic Web pages are generated when the page is requested. Pages that show system settings or log records are examples of dynamic pages.

The Network Component's HTTP server supports both types of web pages. Static web pages are generally stored in the virtual ROM file system. The files are converted into C-code by the FCARM file converter and compiled into code.

Supported Features and Technologies

The Web Server supports the usage of many advanced web technologies:

• A Script Language is used to generate dynamic web pages.
• AJAX Programming is used to create web-applications that are processed on the client-side, thus unloading the web server.
• SOAP Support is necessary for modern user interfaces.
• HTTP Caching enables local caching in the browser and improves the Web Server performance a lot.
• HTTP File Upload allows you to store the complete web site on SD card. The files can be updated via the web interface. This feature is only available with the Full Web Server.
• Access Filtering allows you to filter out the hosts, which are not allowed to connect to the Web Server.
• Multi-language Web Pages can be generated with the help of the integrated Script Language.
• Multi-user Web Authentication allows you to manage user accounts and access rights for each user.

Note

The page HTTP Web Server gives you more information on the actual usage of the functions and how to work with them in a project.

Code Examples

HTTP Server CGI Template

The following source code is part of the HTTP_Server_CGI.c template file. The application specific behaviour of the Script Language may be implemented using this code template:

#include <stdio.h>
#include <string.h>
#include "rl_net.h"
 
// Process query string received by GET request.
void cgi_process_query (const char *qstr) {
  char var[40];

  do {
    // Loop through all the parameters
    qstr = http_get_env_var (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=192.168.0.100"
      if (strncmp (var, "ip=", 3) == 0) {
        uint8_t ip_addr[IP4_ADDR_LEN];
        // Read parameter IP address submitted by the browser
        ip4_aton (&var[3], ip_addr);
         ...
      }
      */
    }
  } while (qstr);
}
 
// Process data received by POST request.
// Type code: - 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.
void cgi_process_data (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 = http_get_env_var (data, var, sizeof (var));
        if (var[0] != 0) {
          // First character is non-null, string exists
          /* Example
          if (strcmp (var, "led0=on") == 0) {
            // ... Switch LED 0 on
          }
          */
        }
      } while (data);
      break;

    case 1:
      // Filename for file upload received
      /* Example
      if (data[0] != 0) {
        // Open a file for writing
        file = fopen (var, "w");
      }
      */
      break;

    case 2:
      // File content data received
      /* Example
      if (file != NULL) {
        // Write data to a file
        fwrite (data, 1, len, file);
      }
      */
      break;

    case 3:
      // File upload finished
      /* Example
      if (file != NULL) {
        // Close a file
        fclose (file);
      }
      */
      break;

    case 4:
      // Other content type data, last packet
      /* Example
      if (strcmp (http_get_content_type(), "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;
  }
}
 
// Generate dynamic web data from a script line.
uint32_t cgi_script (const char *env, char *buf, uint32_t buflen, uint32_t *pcgi) {
  uint32_t len = 0;
 
  // Analyze a 'c' script line starting position 2
  /* Example script
  // c a i <td><input type=text name=ip value="%s" size=18 maxlength=18></td>

  switch (env[0]) {
    case 'a' :
      switch (env[2]) {
        case 'i':
          // Write the local IP address
          len = sprintf (buf, &env[4], ip4_ntoa (IpAddr));
          break;
          ...
      }
      break;
  }
  */
  return (len);
}
 
// Override default Content-Type for CGX script files.
const char *cgx_content_type (void) {
  /* Example
  return ("text/xml; charset=utf-8");
  */
  return (NULL);
}
 
// Override default character encoding in html documents.
const char *http_encoding (void) {
  /* Example
  return ("utf-8");
  */
  return (NULL);
}

HTTP Server Multi-User Template

The following source code is part of the HTTP_Server_Multiuser.c template file, which handles Multi-user Web Authentication for the HTTP server:

#include <string.h>
#include "rl_net.h"
 
// Check if an user account exist in the user database.
uint8_t http_check_account (const char *username, const char *password) {
  /* Example
  if ((strcmp (username, "guest") == 0) && (strcmp (password, "guest") == 0)) {
    // Accept guest account
    return (1);
  }
  */
  return (0);
}
 
// Check if remote user is allowed to access a file on HTTP server.
bool http_file_access (uint8_t user_id, const char *fname) {
  /* Example
  if (user_id == 1) {
    if (strcmp (fname, "system.cgi") == 0) {
      // User "guest" is not allowed to see "system.cgi"
      return (false);
    }
  }
  */
  return (true);
}

HTTP Server Error Template

The following source code is part of the HTTP_Server_Error.c template file. Application specific error pages are implemented using this code template:

#include "rl_net_lib.h"
 
// Keep HTTP Error page size small
HTTP_ERROR http_error = {
  // HTTP Error page header
  "<head><title>Server Error</title></head>"
  "<body>",
 
  // HTTP Error page footer
  "<hr><br>"
  "<i>Keil Embedded WEB Server V2.00, 2013<br>"
  "<a href=http://www.keil.com>www.keil.com</a>"
  " - Embedded Development Tools</i>"
  "</body>",
 
  // HTTP Error 401 - Unauthorized access
  "<h2>Error 401 - Unauthorized Access</h2>"
  "You are not authorized to access this server.",
 
  // HTTP Error 403 - Forbidden
  "<h2>Error 403 - Forbidden</h2>"
  "You don't have permission to access this resource.",
 
  // HTTP Error 404 - Not Found
  "<h2>Error 404 - Not Found</h2>"
  "The requested URL was not found on this server.",
 
  // HTTP Error 501 - Not Implemented
  "<h2>Error 501 - Not Implemented</h2>"
  "The requested Method is not supported."
};

Function Documentation

const char * cgi_content_type

(

const char *

file_ext

)

Add custom MIME type for unsupported file types.

Parameters

[in]

file_ext

filename extension, a null-terminated string.

Returns

pointer to user defined Content-Type or NULL for unknown type.

The function cgi_content_type 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 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 cgi_content_type function does not exist in the project or if it returns a NULL pointer.

The cgi_content_type 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 *cgi_content_type (const char *file_ext) {
  // Example
  if (strcmp (file_ext, "wav") == 0) {
    return ("audio/wav");
  }
  return (NULL);
}

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

Process data received by POST request.

Parameters

[in]	code	callback 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]	data	pointer to POST data.
[in]	len	length of POST data.

Returns

none.

The function cgi_process_data 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:

Code	Data 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 0-terminated string.	Length of a filename.
2	File data	Pointer to data packet received from the host.	Length of data packet.
3	End of file	NULL	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.

The function is in the HTTP_Server_CGI.c module.

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 1460 bytes.
• The XML-POST is generated from the web service application.

Code Example

#include <stdio.h>
#include <string.h>
#include "rl_net.h"
 
// Process data received by POST request.
// Type code: - 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.
void cgi_process_data (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 = http_get_env_var (data, var, sizeof (var));
        if (var[0] != 0) {
          // First character is non-null, string exists
          /* Example
          if (strcmp (var, "led0=on") == 0) {
            // ... Switch LED 0 on
          }
          */
        }
      } while (data);
      break;

    case 1:
      // Filename for file upload received
      /* Example
      if (data[0] != 0) {
        // Open a file for writing
        file = fopen (var, "w");
      }
      */
      break;

    case 2:
      // File content data received
      /* Example
      if (file != NULL) {
        // Write data to a file
        fwrite (data, 1, len, file);
      }
      */
      break;

    case 3:
      // File upload finished
      /* Example
      if (file != NULL) {
        // Close a file
        fclose (file);
      }
      */
      break;

    case 4:
      // Other content type data, last packet
      /* Example
      if (strcmp (http_get_content_type(), "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 cgi_process_query

(

const char *

qstr

)

Process query string received by GET request.

Parameters

[in]

qstr

pointer to the query string.

Returns

none.

The function cgi_process_query 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.

The function is in the HTTP_Server_CGI.c module.

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

#include <stdio.h>
#include <string.h>
#include "rl_net.h"
 
// Process query string received by GET request.
void cgi_process_query (const char *qstr) {
  char var[40];
 
  do {
    // Loop through all the parameters
    qstr = http_get_env_var (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=192.168.0.100"
      if (strncmp (var, "ip=", 3) == 0) {
        int s[4];
        // Read parameter IP address submitted by the browser
        sscanf (&var[3], "%d.%d.%d.%d",&s[0],&s[1],&s[2],&s[3]);
         ...
      }
      */
    }
  } while (qstr);
}

uint32_t cgi_script	(	const char *	env,
		char *	buf,
		uint32_t	buflen,
		uint32_t *	pcgi
	)

Generate dynamic web data from a script line.

Parameters

[in]	env	environment string.
[out]	buf	output data buffer.
[in]	buflen	size of output buffer (from 536 to 1460 bytes).
[in,out]	pcgi	pointer to a session's local buffer of 4 bytes. 1st call = set 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.

• result len | (1U<<31) = repeat flag, the system calls this function again for the same script line.
• result len | (1U<<30) = force transmit flag, the system transmits current packet immediately.

The function cgi_script is what the script interpreter calls when interpreting the script to output the dynamic part of the HTTP response. The script interpreter calls cgi_script for each line in the script that begins with the command c. You must customize the cgi_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 cgi_script function must write the HTTP response.

The argument buflen 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 cgi_script function. You might use this to store:

• loop counters
• number of sent bytes
• pointer to a local status buffer.

The cgi_script function is in the HTTP_Server_CGI.c module.

Note

• The cgi_script function is used by the script interpreter.
• The contents written into the output buffer by the cgi_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 (buflen) 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 cgi_script writes more bytes than buflen 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 cgi_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 cgi_script is called for the first time in each session.
• cgi_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

// Generate dynamic web data from a script line.
uint32_t cgi_script (const char *env, char *buf, uint32_t buflen, uint32_t *pcgi) {
  uint32_t len = 0;
 
  // Analyse a 'c' script line starting position 2
  // c a i <td><input type=text name=ip value="%d.%d.%d.%d" size=18 maxlength=18></td>
 
  switch (env[0]) {
    case 'a' :
      switch (env[2]) {
        case 'i':
          // Write the local IP address
          len = sprintf (buf, &env[4], IpAddr[0], IpAddr[1], IpAddr[2], IpAddr[3]);
          break;
          ...
      }
      break;
  }
  return (len);
}

const char * cgx_content_type

(

void

)

Override default Content-Type for CGX script files.

Returns

pointer to user defined Content-Type.

The function cgx_content_type 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 cgx_content_type function does not exist in the project or if it returns a NULL pointer.

The cgx_content_type function is in the HTTP_Server_CGI.c module. The prototype is defined in rl_net_lib.h.

Note

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

Code Example

const char *cgx_content_type (void) {
  // Example
  if(trueCondition) {
    return ("text/xml; charset=utf-8");
  }
  return (NULL);
}

bool http_accept_client	(	const uint8_t *	ip_addr,
		uint16_t	port
	)

Accept or deny connection from remote HTTP client.

Parameters

[in]	ip_addr	IP address of the remote HTTP client.
[in]	port	port number of the remote HTTP client.

Returns

• true = Connection from the remote client is allowed.
• false = Connection is denied.

The function http_accept_client checks if a connection from a remote client is allowed or not. This enables remote client filtering. You can selectively decide which clients are allowed to connect to the web server.

The argument ip_addr points to a buffer containing the four octets that make up the IP address of the remote machine.

The argument port specifies the port on the remote machine.

The function is in the HTTP_Server_Access.c module.

Note

This function is optional. If it does not exist in the project, the library default function is used. The library default function accepts all remote clients.

Code Example

#include "rl_net.h"
 
// Accept or deny connection from remote HTTP client.
// If this function is missing, all remote clients are accepted.
bool http_accept_client (const uint8_t *ip_addr, uint16_t port) {
  /* Example
  if (ip_addr[0] == 192  &&
      ip_addr[1] == 168  &&
      ip_addr[2] == 0    &&
      ip_addr[3] == 1) {
    // Accept connection.
    return (true);
  }
  // Deny connection.
  return (false);
  */
  return (true);
}

uint8_t http_check_account	(	const char *	username,
		const char *	password
	)

Check if an user account exist in the user database.

Parameters

[in]	username	pointer to username.
[in]	password	pointer to password.

Returns

status information:

• User identification number or
• 0 if the user is not existing.

The function http_check_account checks if a user account exist in the user database for the provided credentials. It is called from the Network Component's Web server to check if the user with provided credentials is allowed to access the web pages or not.

The argument username points to a 0-terminated string representing the user name that was typed in from the browser.

The argument password points to a 0-terminated string representing the password.

The function is in the HTTP_Server_Multiuser.c module.

Note

This function is optional. For single user HTTP authentication or when the HTTP authentication is disabled in the configuration, this function is not required.

Code Example

#include <string.h>
#include "rl_net.h"
 
// Check if an user account exist in the user database.
uint8_t http_check_account (const char *username, const char *password) {
  /* Example
  if ((strcmp (username, "guest") == 0) && (strcmp (password, "guest") == 0)) {
    // Accept guest account
    return (1);
  }
  */
  return (0);
}
 
// Check if remote user is allowed to access a file on HTTP server.
bool http_file_access (uint8_t user_id, const char *fname) {
  /* Example
  if (user_id == 1) {
    if (strcmp (fname, "system.cgi") == 0) {
      // User "guest" is not allowed to see "system.cgi"
      return (false);
    }
  }
  */
  return (true);
}

const char * http_encoding

(

void

)

Override default character encoding in html documents.

Returns

pointer to user defined character set type.

The function http_encoding 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 umlauts characters on German web pages.

Note

This function is optional.

Code Example

const char *http_encoding (void) {
  return ("iso-8859-1");
}

The example above will instruct the web server to generate the following HTTP header:

Content-type: text/html; charset=iso-8859-1

bool http_file_access	(	uint8_t	user_id,
		const char *	fname
	)

Check if remote user is allowed to access a file on HTTP server.

Parameters

[in]	user_id	user identification number.
[in]	fname	name of a file to access.

Returns

• true = File access is allowed.
• false = File access is denied.

The function http_file_access checks if a file access is allowed for a specified user. This enables access protection of sensitive web pages. Protected web pages will not be displayed for unprivileged users. Instead, the Web server shows Error page 403 - Forbidden.

The argument user_id is an user identification number as returned by http_check_account. It identifies the user who is trying to access the specified file.

The argument fname points to a buffer containing the file name of a file, which the user is trying to access. The file name is a 0-terminated string.

The function is in the HTTP_Server_Multiuser.c module.

Note

This function is optional. If the HTTP resource access restriction is not used, this function is not required.

Code Example

#include <string.h>
#include "rl_net.h"
 
// Check if an user account exist in the user database.
uint8_t http_check_account (const char *username, const char *password) {
  /* Example
  if ((strcmp (username, "guest") == 0) && (strcmp (password, "guest") == 0)) {
    // Accept guest account
    return (1);
  }
  */
  return (0);
}
 
// Check if remote user is allowed to access a file on HTTP server.
bool http_file_access (uint8_t user_id, const char *fname) {
  /* Example
  if (user_id == 1) {
    if (strcmp (fname, "system.cgi") == 0) {
      // User "guest" is not allowed to see "system.cgi"
      return (false);
    }
  }
  */
  return (true);
}

const char * http_get_env_var	(	const char *	env,
		char *	ansi,
		uint32_t	maxlen
	)

Process environment variables and convert to ANSI format.

Parameters

[in]	env	pointer to environment variables.
[out]	ansi	output buffer to write converted variable to.
[in]	maxlen	maximum length of environment variable.

Returns

status information:

• pointer to the remaining environment variables to process or
• NULL if there are no more environment variables to process.

The function http_get_env_var 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 maxlen 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 maxlen 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

#include <stdio.h>
#include <string.h>
#include "rl_net.h"
 
// Process query string received by GET request.
void cgi_process_query (const char *qstr) {
  char var[40];
 
  do {
    // Loop through all the parameters
    qstr = http_get_env_var (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=192.168.0.100"
      if (strncmp (var, "ip=", 3) == 0) {
        int s[4];
        // Read parameter IP address submitted by the browser
        sscanf (&var[3], "%d.%d.%d.%d",&s[0],&s[1],&s[2],&s[3]);
         ...
      }
    }
  } while (qstr);
}

Referenced by cgi_process_data(), and cgi_process_query().

uint8_t http_get_user_id

(

void

)

Retrieve the user identification.

Returns

user identification number (0 = system administrator).

The function http_get_user_id retrieves the user identification number when the web pages are protected with user authentication. It can be used to generate a web page, whose content is based on the connected user. This function is normally called from the cgi_script function.

The http_get_user_id is a system function that is in the Network Component library.

Note

This function returns a value of 0 for system administrator account.

Code Example

uint16_t cgi_script (const char *env, char *buf, uint16_t buflen, uint32_t *pcgi) {
  uint8_t uid;
  ..
    case 'd':
      // System password - file 'system.cgi' 
      switch (env[2]) {
        case '0':
          // Display the user name on web page. 
          uid = http_get_user_id ();
          len = sprintf((char *)buf,(const char *)&env[4],
                        (uid == 0) ? "admin" : users[uid-1]);
          break;
        case '1':
           ..
          break;
      }
      break;
   ..
}  

void http_server_fclose

(

void *

file

)

Close a file previously open in HTTP server.

Parameters

[in]

file

pointer to the file to close.

Returns

none.

The function http_server_fclose closes the file identified by the file stream pointer in the function argument.

The function interfaces to the File System Component and will be called by the Network Component automatically. If another file system will be used, refer to the reference implementation in the HTTP_Server_FS.c module.

char * http_server_fgets	(	void *	file,
		char *	buf,
		uint32_t	size
	)

Read a string from a file in HTTP server.

Parameters

[in]	file	pointer to the file to read from.
[out]	buf	output buffer to write data to.
[in]	size	size of output buffer.

Returns

status information:

• Pointer to string on success
• NULL in case of an error.

The function http_server_fgets reads up to size bytes from the file identified by the file stream pointer in the function argument.

The argument buf is a pointer to the buffer which stores the data.

The function interfaces to the File System Component and will be called by the Network Component automatically. If another file system will be used, refer to the reference implementation in the HTTP_Server_FS.c module.

Note

The function is used by the script interpreter.

void * http_server_fopen

(

const char *

fname

)

Open a file for reading in HTTP server.

Parameters

[in]

fname

name of the file to open.

Returns

status information:

• Pointer to an open file or
• NULL in case of an error.

The function http_server_fopen opens a file for reading.

The argument fname specifies the name of the file to open. If the file does not exist, the function fails and returns NULL.

The argument fname is percent-encoded. This means that all reserved characters in a file name are escaped.

The function interfaces to the File System Component and will be called by the Network Component automatically. If another file system will be used, refer to the reference implementation in the HTTP_Server_FS.c module.

uint32_t http_server_fread	(	void *	file,
		uint8_t *	buf,
		uint32_t	len
	)

Read block of data from a file in HTTP server.

Parameters

[in]	file	pointer to the file to read from.
[out]	buf	block of memory to write data to.
[in]	len	length of data to read in bytes.

Returns

number of bytes successfully read.

The function http_server_fread reads len bytes from the file identified by the file stream pointer in the function argument.

The argument buf is a pointer to the buffer where the function stores the read data.

The function interfaces to the File System Component and will be called by the Network Component automatically. If another file system will be used, refer to the reference implementation in the HTTP_Server_FS.c module.

Note

The function must read len bytes. The Web Server stops reading and closes the file if the return value is less than len bytes.

uint32_t http_server_ftime

(

const char *

fname

)

Retrieve last modification time of a file.

Parameters

[in]

fname

name of the file.

Returns

last modification time in UTC format.

The function http_server_ftime reads the time when the file identified by the fname was last modified.

The function interfaces to the File System Component and will be called by the Network Component automatically. If another file system will be used, refer to the reference implementation in the HTTP_Server_FS.c module.

netStatus http_server_get_client	(	uint8_t *	ip_addr,
		uint8_t *	mac_addr
	)

Get IP and MAC address of connected remote machine.

Parameters

[out]	ip_addr	pointer to IP address.
[out]	mac_addr	pointer to MAC address.

Returns

status code that indicates the execution status of the function as defined with netStatus.

The function http_server_get_client obtains information about the remote machine and records the IP address and MAC address in memory.

The argument ip_addr is the remote machine IP address.

The argument mac_addr is the remote machine MAC address.

Note

• You can use the IP address or MAC address information to restrict which remote machines are allowed to perform system changes.
• For PPP and SLIP links, the function records 00-00-00-00-00-00 as the MAC address.

Code Example

//coming soon

const char * http_server_get_content_type

(

void

)

Get Content-Type HTML header, received in XML post request.

Returns

pointer to content type header, a null-terminated string.

The function http_server_get_content_type returns a pointer to the Content-Type html header, which was received with a XML or any other type POST request. You can use this function to check for the content type, which was submitted by a web service application.

Note

When a web service application sends a request to a web server, it specifies the Content-Type in the HTTP header that is sent to the web server. This information is processed by the Network Component and stored internally.

Code Example

void cgi_process_data (uint8_t code, const char *data, uint32_t len) {
  char var[40];
 
  switch (code) {
    ...
    case 4:
      // Other content type data, last packet
      // Example
      if (strcmp (http_get_content_type(), "text/xml; charset=utf-8" == 0) {
        // Content type xml, utf-8 encoding
         ...
      }
      break;
 
    default:
      // Ignore all other codes
      break;
  }
}

const char * http_server_get_lang

(

void

)

Retrieve the preferred language setting from the browser.

Returns

pointer to the language code, a null-terminated string.

The function http_server_get_lang retrieves the preferred language setting from the browser. You can use this information to implement automatic language selection for your embedded web pages.

Note

• When a web browser requests a web page, it specifies the preferred language in the HTTP header that is sent to the web server. This information is processed by the Network Component and stored internally.
• You can set the language preference in Internet Explorer by selecting Tools -> Internet Options -> Languages. In Mozilla Firefox, you can set the language preference by selecting Options -> Options -> Content -> Languages.

Code Example

uint32_t cgi_script (const char *env, char *buf, uint32_t buflen, uint32_t *pcgi) {
  uint32_t len = 0;
  char *lang;
 
  switch (env[0]) {
     ..
    case 'e':
      // Browser Language - file 'language.cgi' 
      lang = http_get_lang();
      if (strcmp (lang, "en") == 0) {
        lang = "English";
      }
      else if (strcmp (lang, "en-us") == 0) {
        lang = "English USA";
      }
      else if (strcmp (lang, "de") == 0) {
        lang = "German";
      }
      else if (strcmp (lang, "de-at") == 0) {
        lang = "German AT";
      }
      else if (strcmp (lang, "fr") == 0) {
        lang = "French";
      }
      else {
        lang = "Unknown";
      }
      len = sprintf(buf,&env[2],lang,http_get_lang());
      break;
  }
  return (len);
}

int32_t http_server_get_session

(

void

)

Get current session number of HTTP server.

Returns

current session number.

The function http_server_get_session returns the current session number of the HTTP server running on the Network Component. The session number can be any value between 0 and HTTP_SERVER_NUM_SESSIONS, defined in Net_Config_HTTP_Server.h.

Note

Storing the HTTP query string in a single global variable can result in the HTTP server sending the wrong reply to a client when several clients try to access a dynamic HTTP page at the same time. Hence, it is better to have a separate variable for each session, for example an array of query strings.

Code Example

// Should be the same value as set in 'Net_Config_HTTP_Server.h' file. 
#define HTTP_SERVER_NUM_SESSIONS 10
 
int32_t answer[HTTP_SERVER_NUM_SESSIONS];
 
uint32_t cgi_script (const char *env, char *buf, uint32_t buflen, uint32_t *pcgi)
  uint32_t len = 0;
  int32_t http_session;
  ..
  http_session = http_server_get_session ();
  len += sprintf (buf+len,"Answer is: %d",answer[http_session]);
   ..
  return (len);
}

uint32_t http_utc_time	(	uint8_t	hr,
		uint8_t	min,
		uint8_t	sec,
		uint8_t	day,
		uint8_t	mon,
		uint16_t	year
	)

Convert generic time to UTC time format.

Parameters

[in]	hr	hours [0..23].
[in]	min	minutes [0..59].
[in]	sec	seconds [0..59].
[in]	day	day [1..31].
[in]	mon	month [1..12].
[in]	year	year [1980..2107].

Returns

time converted to UTC format.

The function http_utc_time converts the time arguments into a UTC time format.

Code Example

// Retrieve last modification time of a file.
uint32_t http_server_ftime (const char *fname) {
  fsFileInfo *info;
  uint32_t utc;
 
  info = (fsFileInfo *)mem_alloc (sizeof (fsFileInfo));
  info->fileID = 0;
  utc = 0;
  if (ffind (fname, info) == fsOK) {
    // File found, convert creation time to UTC format.
    utc = http_utc_time (info->time.sec, info->time.min, info->time.hr,
                         info->time.day, info->time.mon, info->time.year);
  }
  mem_free ((NET_FRAME *)info);
  return (utc);
}

Referenced by http_server_ftime().