Hypertext Mark-up Language (HTML) is the primary language for formatting web pages. With HTML, you describe what a page must look like, what types of fonts to use, what colour the text should be, where paragraph marks must come, and many more aspects of the document.

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 supports both of them. Static web pages are generally stored in the ROM file system. The files are converted into C-code by the FCARM file converter and compiled into code.

There are basically two types of web servers available in the Network Component. The Compact Web Server can store HTML files only in its ROM. An update of these pages is not possible. The Full Web Server uses the File System Component to store data on a storage device. These files can be updated in the field. Both web servers have integrated several advanced features, which support the usage of many advanced web technologies:

A Script Language is used to generate Dynamic Web pages.
AJAX Programming allows you to move the web page processing from the web server to the client browser.
SOAP Support allows you to produce some cutting edge user interfaces.
Web Pages store the actual content that will be delivered by the web server.
HTTP Caching supports the local caching at the browser and improves the Web Server performance a lot.
Web on SD Card allows you to store the complete web site resource files on SD Card. Web files can be updated with HTTP file upload.
Access Filtering allows you to filter out the hosts, which are not allowed to connect to the Web Server.
Multi-language Web Pages help you to generate language specific web pages with the help of the integrated script language.
Multi-user Web Authentication allows you to manage user accounts and access rights for each user.

Script Language

The Network Component provides a small script language which can be used to generate truly dynamic web pages. The HTTP Server processes the script source file line by line and calls the CGI functions as needed. The output from a CGI function is sent to the web client as a part of the web page.

Each script line starts with a command character which specifies a command for the script interpreter. The script language itself is simple and works as follows:

Command	Description
i	Commands the script interpreter to include a file from the file system and to output the content on the web browser.
t	Commands that the line of text that follows is to be output to the browser.
c	Calls a C function from the HTTP_Server_CGI.c file. The function may be followed by the line of text which is passed to cgi_script() as a pointer to an environment variable.
#	This is a comment line and is ignored by the interpreter.
.	Denotes the last script line.

Here is an example of a web page written in the script language. This web page edits or changes the system password. The web page is stored in three files (two are static, and the third (main file) is the script file that generates dynamic data). The script system.cgi contains the following:

i password_h.inc
c d 1 <TR><TD><IMG SRC=pabb.gif>Authentication</TD><TD><b>%s</b></TD></TR>
t <TR><TD><IMG SRC=pabb.gif>Password for user 'admin'</TD>
c d 2 <TD><INPUT TYPE=TEXT NAME=pw SIZE=10 MAXLENGTH=10 VALUE="%s"></TD></TR>
t <TR><TD><IMG SRC=pabb.gif>Retype your password</TD>
c d 2 <TD><INPUT TYPE=TEXT NAME=pw2 SIZE=10 MAXLENGTH=10 VALUE="%s"></TD></TR>
i password_f.inc
.

The web page header, which is static and does not change when the web page is generated, is moved into the separate header file password_h.inc. The content of the included page header file is:

<HTML>
  <HEAD>
    <TITLE>System Settings</TITLE>
  </HEAD>
  <BODY TEXT=#000000 BGCOLOR=#ccddff LINK=#0000FF VLINK=#0000FF ALINK=#FF0000>
  <H2 ALIGN=CENTER>System Settings</H2>
  <FORM ACTION=index.htm METHOD=POST NAME=CGI>
  <TABLE BORDER=0 WIDTH=99%>
  <TR BGCOLOR=#aaccff>
    <TH WIDTH=40%>Item</TH>
    <TH WIDTH=60%>Setting</TH>
  </TR>

It is included into the generated web page with the following script command:

i password_h.inc

The web page footer is also static and is moved into the password_f.inc file. It is not changed when the web page generates but is simply included in the script.

  <TR>
    <TD>&nbsp;</TD>
    <TD>&nbsp;</TD>
  </TR>
  <TR>
    <TD></TD>
    <TD align="right">
      <INPUT TYPE=SUBMIT NAME=set VALUE="Change" id="sbm">
      <INPUT TYPE=RESET VALUE="Undo">
      <INPUT TYPE=BUTTON VALUE="Home" OnClick="location='/index.htm'">
    </TD>
  </TR>
  </FORM>
  <p>This page allows you to change the system <b>Password</b>, for the username
    <b>admin</b>. Default <b>realm</b>, <b>user</b> and <b>password</b> can be set
    in configuration file. This Form uses a <b>POST</b> method to send data back to
    a Web server. You need to click on <b>Change</b> button to activate the changes.
  </p>
  </BODY>
</HTML>

This is how the generated web page looks like, with the dynamically generated items in the Setting column:

You can see the HTML source code of this web page. This data is actually sent to the web client when the client requests the web page system.cgi. The script file is processed by the script interpreter, and the following data is generated by the Web Server. You can compare the generated HTML source with the script file to see where the CGI interface comes in.

<HTML>
  <HEAD>
    <TITLE>System Settings</TITLE>
  </HEAD>
  <BODY TEXT=#000000 BGCOLOR=#ccddff LINK=#0000FF VLINK=#0000FF ALINK=#FF0000>
  <H2 ALIGN=CENTER>System Settings</H2>
  <FORM ACTION=index.htm METHOD=POST NAME=CGI>
  <TABLE BORDER=0 WIDTH=99%>
  <TR BGCOLOR=#aaccff>
    <TH WIDTH=40%>Item</TH>
    <TH WIDTH=60%>Setting</TH>
  </TR>
  <TR><TD><IMG SRC=pabb.gif>Authentication</TD><TD><b>Enabled</b></TD></TR>
  <TR><TD><IMG SRC=pabb.gif>Password for user 'admin'</TD>
  <TD><INPUT TYPE=TEXT NAME=pw SIZE=10 MAXLENGTH=10 VALUE="test"></TD></TR>
  <TR><TD><IMG SRC=pabb.gif>Retype your password</TD>
  <TD><INPUT TYPE=TEXT NAME=pw2 SIZE=10 MAXLENGTH=10 VALUE="test"></TD></TR>
  <TR>
    <TD>&nbsp;</TD>
    <TD>&nbsp;</TD>
  </TR>
  <TR>
    <TD></TD>
    <TD align="right">
      <INPUT TYPE=SUBMIT NAME=set VALUE="Change" id="sbm">
      <INPUT TYPE=RESET VALUE="Undo">
      <INPUT TYPE=BUTTON VALUE="Home" OnClick="location='/index.htm'">
    </TD>
  </TR>
  </FORM>
  <p>This page allows you to change the system <b>Password</b>, for the username
    <b>admin</b>. Default <b>realm</b>, <b>user</b> and <b>password</b> can be set
    in configuration file. This Form uses a <b>POST</b> method to send data back to
    a Web server. You need to click on <b>Change</b> button to activate the changes.
  </p>
  </BODY>
</HTML>

Code Example for HTTP_Server_CGI.c

#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 XML encoded POST data (single or last stream).
//            - 5 = the same as 4, but with more XML 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:
      // XML encoded content type, last packet
      /* Example
      if (strcmp (http_get_content_type(), "text/xml; charset=utf-8" == 0) {
        // Content type xml, utf-8 encoding
         ...
      }
      */
      break;
    case 5:
      // XML encoded content type, more to follow
      // ... Process xml 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);
}

Note

The script files use the reserved filename extension of cgi. Using the cgi filename extension for script files is mandatory for the Web Server script interpreter to recognize and process the script files.
The script line length is limited to 120 characters.

AJAX Programming

AJAX is a group of web development techniques used on the client-side to create interactive web applications. AJAX is a shorthand for Asynchronous JavaScript and XML. With AJAX web applications can retrieve data from the server asynchronously in the background without interfering with the display and behaviour of the existing page.

AJAX is based on JavaScript and HTTP requests. It is not a new programming language, but a new way to use existing standards. JavaScript is the most popular language for AJAX programming due to its inclusion in and compatibility with the majority of modern web browsers.

How it works

In Ajax programming, the browser sends a standard HTTP request to the web server, such as GET or POST. The web server checks the file extension of the requested file. If the file extension is cgx, the requested file is an XML script file. This file is processed by internal script interpreter running on the web server. As a result the XML response is generated and sent back to the browser.

Here is a an example of a typical data flow:

Web browser sends a standard HTTP GET request:
GET /ad.cgx HTTP/1.1\r\n

Web server processes the script file ad.cgx and sends the XML response:
<form><text><id>ad_value</id><value>0x06A</value></text></form>

The JavaScript XML parser in the web browser processes this response and updates the object with id ad_value on the web page.
<input type="text" readonly size="10" id="ad_value" value="0x06A">

XML

XML, a shorthand for Extensible Markup Language, is a simple, very flexible text format. It is a generic framework for storing any amount of any data whose structure can be represented as a tree. It allows the user to create the mark-up elements. XML has become the almost universally supported way of exchanging documents and data across applications and platforms. The benefits of using XML technology for web page update are obvious:

Instead of several files, only one small XML file is transferred for web page update.
This allows faster, flicker-free screen updates.
The used LAN bandwidth is very small.
The web server can easily handle more clients at the same time.

The components of XML file are tagged. You must use this format for generated XML responses. The object ID's and their values must be specified within XML body - enclosed with tags <form> and </form>. The following objects are defined:

Text object:
<text>

<id>text_id</id>

<value>text_value</value>

</text>
Checkbox object:
<checkbox>

<id>checkbox_id</id>

<checked>true/false</checked>

</checkbox>
Select object:
<select>

<id>option_id</id>

<value>true/false</value>

</select>
Radio object:
<radio>

<id>radio_id</id>

<value>true/false</value>

</radio>

The other HTTP objects are optional. You can add them yourself.

XML Example

Here is an example of a XML web page update written in the script language. This web page displays the value of an analog input (AD). When first opened, a complete AD web page is generated by the web server. Later, when you enable the periodic update of the page, this page is updated with a Java Script function updateMultiple(). This function is in the xml_http.js file.

The script file ad.cgx contains the following:
t <form>

t <text>

t <id>ad_value</id>

c x<value>0x%03X</value>

t </text>

t </form>

.

The script interpreter processes this file and generates the following response:
<form><text><id>ad_value</id><value>0x06A</value></text></form>

The XML response does not contain any spaces or CR-LF characters between the XML tags.

The Java Script function periodicUpdateAd() activates the periodic time-outs for the page update. This function is specific for the AD page module and is included in the ad.cgi script file:
function periodicUpdateAd() {

if(document.getElementById("adChkBox").checked == true) {

updateMultiple(formUpdate,plotADGraph);

ad_elTime = setTimeout(periodicUpdateAd, formUpdate.period);

}

else

clearTimeout(ad_elTime);

}

The update interval and URL are defined in the formUpdate object. When update interval expires, a XML response is requested from the URL specified in this Java object.
var formUpdate = new periodicObj("ad.cgx", 500);

The actual update of the analog bar and AD values on the web page is done by the Java function plotADGraph():
function plotADGraph() {

adVal = document.getElementById("ad_value").value;

numVal = parseInt(adVal, 16);

voltsVal = (3.3*numVal)/1024;

tableSize = (numVal*100/1024);

document.getElementById("ad_table").style.width = (tableSize + '%');

document.getElementById("ad_volts").value = (voltsVal.toFixed(3) + ' V');

}

This function is called as a callback function from the updateMultiple() Java function.

Note

The XML script files use the reserved filename extension cgx. Using the cgx file extension for XML script files is mandatory for the web Server script interpreter to recognize and process the XML script files.
There must be no spaces or CR-LF characters between XML tags, or some web browsers might have problems when parsing the XML response.
The script line length is limited to 120 characters.

SOAP Support

The Simple Object Access Protocol (SOAP), is a XML-based protocol to let applications exchange information over HTTP. It is created to enable communication between applications. It is important for application development to allow Internet communication between programs. A better way to communicate between applications is over HTTP, because HTTP is supported by all Internet browsers and servers. SOAP provides a way to communicate between applications running on different operating systems, with different technologies and programming languages.

SOAP Interface

SOAP messages in HTTP consist of a POST request, submitted by the client, and a response generated by the web server. The Embedded Web server handles SOAP messages differently. Instead of processing them internally and notifying the user via a callback function, it delivers a complete SOAP message to the user via the callback function.

In general, SOAP messages are large. Embedded systems that run a web server with SOAP, need much more RAM for message buffering and processing. A typical configuration would have:

a few MBytes of RAM.
a SD Card for deploying a web service application.

The following extensions have been added to the web server:

the cgi_process_data function has been extended with code 4 and 5 to allow processing of fragmented large POST messages.
the Content-Type HTTP header for XML-encoded POST requests is buffered. The function http_server_get_content_type returns a pointer to the Content-Type string, which was received in the XML POST request.
the Content-Type header for the response can be defined by the user in the cgx_content_type function.
the http_server_get_session function is used to identify which web server session has called a cgi_process_data callback function, if two or more clients have sent XML-POST requests at the same time.
the HTTP Caching improves the web server performance a lot when serving large web service applications.

Large POST Messages

When the web server receives a POST request, the server checks the Content-Type header. All XML-encoded content types are not processed further, but the data is delivered to the user in a callback function. It is the responsibility of the user to correctly assemble large POST messages, because they are fragmented and delivered from several TCP packets. For the first and optional subsequent packets, the web server calls the callback function with code 4:

cgi_process_data (4, dat, len);

The user should now start to buffer the data.

For the last data packet, the web server calls the callback function with code 5:

cgi_process_data (5, dat, len);

The XML-POST data is now complete and the user can start parsing the XML encoded data. In addition the user might check what was the Content-Type with the function http_server_get_content_type.

Web Pages

The web pages for the web servers are created in the same way as the web pages for any other web server. You can use any text editor to edit the HTML code. It is a good idea to preview the page. Here are a few guidelines:

Design a web page in HTML code. You can add images and java script functions as well.
If the web page needs to show dynamic values, code this page in the Script Language. You must also update the CGI callback function, cgi_script, accordingly. It is a good practice to program the script code and cgi_script in parallel. Note that the module HTTP_Server_CGI.c must be included in your project.
If needed, draw or add images, which can be of type gif, bmp, jpg, or png for example. A good choice is to select the image type with the best compression because these files are included in the code. Large image files might increase the application code size by a large extent.
Add all the web files to the FCARM tool.

Default Page

When you type the URL or IP address in the browser's address bar, the web server sends the content of the index.htm web page. This is the default page, which is opened, as long as no filename is specified in the URL. If you enter the complete URL, including a filename (for example http://mcb1700/ad.htm), then the web server tries to open this page.

The default page index.htm is a static page. This means the content of this page is stored on the web server and sent unmodified to the web client on request. Usually this page contains links to other static or dynamic pages on the web server.

Sometimes, a dynamic page is preferred as a default web page. This is also supported. When a browser requests a default web page, the web server tries to open index.htm as default web page. If this page does not exist, web server in the next step tries to open index.cgi as a default page. If this page is also not existing, then the web server responds with Error 404 - Not Found.

Note: If you want to use a dynamic default page, then the file index.htm must not exist on the web server.

Error Pages

Both web servers show an error page when encountering error conditions.

Error Code	Title	Description
401	Unauthorized Access	You are not authorized to access this server
403	Forbidden	You don't have permission to access this resource
404	Not Found	The requested URL was not found on this server
501	Not Implemented	The requested method is not supported

The error pages above are already included in the Network Component. If you want to modify them, you must copy the module HTTP_Server_Error.c to your project and customize it. To add the module to your project, simply right-click on the Source group, select Add New Item to Group, then click on User Code Template and scroll in the template files list until you find the HTTP Server Error Messages template. Modified error pages must be small because they are sent in a single TCP packet.

Code Example

#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."
};

HTTP Caching

HTTP protocol supports local caching of static resources by the browser. Most web pages include resources that change infrequently, such as CSS files, image files, JavaScript files, and so on. These resources take time to download over the network, which increases the time it takes to load a web page. HTTP caching allows these resources to be saved, or cached, by a browser. Once a resource is cached, a browser can refer to the locally cached copy instead of having to download it again on subsequent visits to the web page.

The advantage of caching is obvious:

The page load time for subsequent user visits is reduced, eliminating numerous HTTP requests for the required resources
The total payload size of the responses is reduced.

How it works

The web server supports HTTP local caching by the browser. For static resources (basically everything except the scripts themselves), the server sends the HTTP header with the last modified date tag in the response.

Resource not cached

Here is an example. The browser opens a web page, which is not yet cached locally.

The browser opens a default page:
http://mcb1700

This generates the following HTTP request for the web server:
GET / HTTP/1.1

Accept: image/gif, image/jpeg, image/pjpeg, image/pjpeg, application/x-

shockwave-flash, application/vnd.ms-excel, application/vnd.ms-powerpoint,

application/msword, application/xaml+xml, application/vnd.ms-xpsdocument,

application/x-ms-xbap, application/x-ms-application, *\/*

Accept-Language: en-us

User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1;

Trident/4.0; .NET CLR 1.1.4322; InfoPath.1; .NET CLR 2.0.50727; .NET CLR

3.0.04506.30; .NET CLR 3.0.04506.648; .NET CLR 3.0.4506.2152; .NET CLR

3.5.30729)

Accept-Encoding: gzip, deflate

Host: mcb1700

Connection: Keep-Alive

The web server opens a default page index.htm and sends it to the browser with the following HTTP header:
HTTP/1.1 200 OK

Server: Keil-EWEB/2.1

Content-Type: text/html

Last-Modified: Thu, 19 Nov 2009 07:46:25 GMT

Connection: close

// and the content of 'index.htm'

The browser, upon receiving the Last-Modified HTTP header, stores this file to a local cache together with the URL and the date tag.

Resource cached

When the browser tries to open the same page again, it first checks the local cache. The file index.htm is already there, so it sends a different request to the Web server.

The browser sends a different http header in the request:
GET / HTTP/1.1

Accept: *\/*

Accept-Language: en-us

User-Agent: Mozilla/4.0 (compatible; MSIE 7.0; Windows NT 5.1;

Trident/4.0; .NET CLR 1.1.4322; InfoPath.1; .NET CLR 2.0.50727; .NET CLR

3.0.04506.30; .NET CLR 3.0.04506.648; .NET CLR 3.0.4506.2152; .NET CLR

3.5.30729)

Accept-Encoding: gzip, deflate

If-Modified-Since: Thu, 19 Nov 2009 07:46:25 GMT

Host: mcb1700

Connection: Keep-Alive

Now, the web server is also informed that the requested file is cached. The web server checks the date, if the browser caches the same file version. If the date tags are equal, the Web server sends only a short response:
HTTP/1.1 304 Not Modified

Server: Keil-EWEB/2.1

Connection: close

The browser now uses the locally cached index.htm

Outdated resource cached

If the date tags are not equal, the file cached by browser is outdated. The web server sends the updated index.htm. The browser updates the local cache and uses an updated file.

HTTP/1.1 200 OK
Server: Keil-EWEB/2.1
Content-Type: text/html
Last-Modified: Thu, 19 Nov 2009 09:38:54 GMT
Connection: close
// and the new content of 'index.htm'

Internal Web

The internal web pages are included and compiled into the code. When the FCARM file converter reformats the web files into a single C-file, a timestamp is also added.

const uint32_t imageLastModified = 1380695329;

This time is used by the web server as the File Modification Date. It is specified in UTF format. The web server uses this date in the HTTP responses.

File caching improves the web server performance a lot. The following table lists the times required to load the default page from an example:

index.html not cached	index.html cached
447.5 ms	53.1 ms

External Web

The web server also supports the browser local caching of its pages stored on SD Card. In general, files on a SD Card are bigger, thus the performance gain is much better. The available space for internal web pages is limited to the size of the internal flash memory. Thus, all large images, Java script archives and other large web resources, have to be located on an externally attached SD Card.

Static Web Resources

The static web resource files are copied to a SD Card when the application is built. They will not be modified later. You might use a SD Card Reader attached to your PC to copy the files. In this case, the file modification date is set correctly by the PC. If you use an embedded application to copy the files, the file modification date is most likely set to the File System default time. However, this does not create any problems for browser local caching. Once the web is locally cached by the browser, the cache is always valid and is used in subsequent browser requests.

Using Web Update

Web resource files, which are updated later with one of the update options provided by the Network Component, are dynamic Web resource files. You must provide the file modification date and time to the File System. If this information is not available, the File System uses a default file modification time. This might create troubles in local caching by the browser.

If you upload an updated web page with a wrong file modification date to the server, the web server is not able to recognize the updated files. It always reports the same Last-Modified date. The browser then uses the locally cached page instead. So the updated pages will never be used. You can force the browser to load the updated pages by manually clearing the browser cache and reloading the web page.

Note: If the File System does not have access to Real Time Clock information, the web server will not work for updated Web pages.

Web on SD Card

The Full Web Server supports storing of web pages on a SD Card, which is attached to the embedded system. This is useful if you want to update or change the web content remotely. In this case, the File System Component is used, which must be configured for a target device Memory Card Drive.

You can use any of the update methods to change the content of web pages:

HTTP File Upload: The web files are uploaded using a web browser. HTTP Server must be configured for the file upload.
FTP Server: The web files are uploaded and managed with a FTP Client.

Web Update

When the Full Web Server tries to open a web page, it searches the external file system first. This is usually an externally attached SD Card. As the Compact Web Server is not configured to use an external file system, it searches only the internal ROM file system.

If the requested file is found on SD Card, the content is sent to the web client. If the requested file does not exist on SD Card, the file with the same name is opened on the internal ROM file system and transferred to the web client. This concept allows you to simply replace the web content from internal ROM file system with a new one, that is uploaded to the external SD Card.

You should carefully update the cgi and cgx script files, as changes in the script files usually reflect also a changes in the application code, which is in the module HTTP_Server_CGI.c. If you have made a mistake in the uploaded script files, the web pages might not be accessible any more.

To enable the SD-Card File System, you need the select the Web Server in the Manage Run-Time Environment window under Network:Service:Web Server. The file HTTP_Server_FS.c will be automatically added to your project. This file contains the following interface functions for the File System and SD-Card:

http_server_fopen - open a file for reading in the web server.
http_server_fclose - close a file that was previously opened.
http_server_fread - read a block of data from a file in the web server.
http_server_fgets - read a string from a file in the web server.
http_server_ftime - retrieve the last modification time of a file.

Access Filtering

For access filtering the function http_accept_client is used. It is part of the file HTTP_Server_Access.c. You need to adapt the function to the application's needs.

Code Example HTTP_Server_Access.c

#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);
}

Multi-language Web Pages

For retrieving the preferred language from the browser, the function http_server_get_lang is used. Please refer to the reference section for further information.

Multi-user Web Authentication

Multi-user authentication allows you to create different profiles for different users or groups of users. The profiles define the access rights to different resources on the web server. All users who are allowed to access the web server are in the user database. The multi-user login also allows the Web server to create different pages depending on user.

If you want to use multi-user authentication, you must select Enable User Authentication in the Net_Config_HTTP_Server.h configuration file. In addition, for proper multi-user authentication, you need to add the HTTP_Server_Multiuser.c file to your project.

The account defined in the Net_Config_HTTP_Server.h configuration file is a system administrator account, which has no restrictions. All other accounts are created in a separate HTTP_Server_Multiuser.c module. To add the module to your project, simply right-click on the Source group, select Add New Item to Group, then click on User Code Template and scroll in the template files list until you find the HTTP Server Multi-User template.

The following functions are included in this module:

http_check_account - checks if the user account exists for the provided credentials.
http_file_access - check if the access to the file is allowed for a provided user.

The following function is included in the Network Component library rl_net.h:

http_get_user_id - retrieves the user identification number for the user, which is trying to access the resource.

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);
}

Note

If the HTTP_Server_Multiuser.c is not added to the project, but Authentication is enabled, the web server runs in single user authentication mode.
You can disable a system administrator account, if you set for the Authentication Username an empty string.

HTTP Web Server Configuration

HTTP Web Server Configuration File

The HTTP server configuration file Net_Config_HTTP_Server.h contains the following settings:

Number of Sessions specifies the number of simultaneously active HTTP sessions. This number should be increased when delays are observed while loading pages in a web browser. This increases also total RAM usage. Web pages can contain many objects (like GIF or JPEG images). The remote HTTP client (web browser) opens multiple connections when downloading such pages. If there are not enough sessions configured for a parallel load, excess connections are rejected by the HTTP server. The browser then starts the socket recovery mode and retries to load missing resources. This recovery causes a delay which varies for different browsers.
Port Number specifies the listening TCP port number. The default HTTP server listening port is 80.
Server-id header specifies the custom HTTP server header identification. This identification is contained in each Web server response packet. When this option contains an empty string, a default Server-Id from the library is used instead.
The Enable User Authentication switch enables or disables authentication with a username and a password.
- Authentication Realm is the string which is displayed in the browser's authentication dialogue if an authentication is required. This is a zero terminated string.
- Authentication Username is the username for authentication.
- Authentication Password is the default password, that must be stored in non-volatile memory. The user can change the password later.