This paper covers fundamental concepts of HTTP and how the Barracuda Embedded Web Server can be used in an embedded device.
Depending on your knowledge of the various technologies covered, it may not be necessary to read each section, although each section also presents some of Barracuda's unique features. This paper also assumes a basic understanding of HTML, C and C++.
This article can be printed, although the online edition features interactive examples. The whitepaper is best viewed online, but you can also download a PDF version.
The Hyper Text Transfer Protocol(HTTP) is a text-based Remote Procedure Call (RPC) protocol that can transfer any type of data between the client and server. An HTTP client opens a connection and sends a request message to an HTTP server. The server then returns a response message.
The HTTP header contains an initial line and a number of header lines followed by an optional body. The initial line of the request and the response are different. In a request, the initial line contains the HTTP method and the requested resource, while in a response, it contains the response protocol version, a status code, and a status message. The most common HTTP methods, the RPC type, are GET and POST, where GET usually means "Server, please give me this resource" and POST usually means "Server, here is my data", though this should be decided by the resource.
The Barracuda embedded Web Server treats all resources as executing units. A Barracuda executing unit can be a physical resource such as a page. A virtual resource can also be a container that can contain other executing units. An executing unit is just a plugin to the web-server. The Barracuda embedded web-server comes with a number of executing units such as a directory unit that can directly read from a ZIP file and present the content to a browser client. Other plugins, such as the EventHandler, can be installed as well. The above HTTP command example sends two parameters, fridgeTemp and freezerTemp to an executing unit in the Barracuda Virtual File System at location "/refrigerator/temperature/". A Directory Executing Unit is called HttpDir and a Page Executing Unit is called HttpPage. An HttpPage and HttpDir can be extended, or in Java terminology, you can extend the base classes and implement your own "live resource".
Most people associate a Web Server as a way of serving HTML content to a browser. An advanced Web Server such as Barracuda can do much more than serving HTML files. We briefly discussed above how one can use Barracuda as a general purpose HTTP stack and how one can do regression tests by exporting internal objects in a device to script programs running on a host computer.
A naive Web Server treats resources as files and either has no support for dynamically generated content or forces the Web-Designer to use certain predefined directories for generating dynamic content. For example, a server supporting CGI forces the web-designer to use the /cgi/ directory for dynamic content generation and data exchange.
Barracuda supports Executing Units, thus a resource is a "live resource" i.e. it is a mini program one can plug into the server. In Barracuda, a resource is typically derived from the HttpPage type. A more complex design can use the HttpDir type to design a collection of virtual resources. A Barracuda resource can dynamically generate anything from binary data such as streaming audio to plain text. A resource is typically generating HTML when the client is a browser.
A typical scenario when using a browser to control a device is for the browser to initially request a certain resource in the server. The resource might respond by sending back an HTML page containing information about that particular resource when receiving an HTTP GET command. For example, a resource at "refrigerator/temperature/" sends back information about the current temperature in the refrigerator and freezer. The HTML sent to the browser can for example contain an HTML form, which the user can use for setting a new temperature in the device.
| HTML form example | The HTML form source code |
|---|---|
|
|
<form method="post">
<table>
<tr>
<td>Refrigerator Temperature:</td>
<td><input type="text" name="fridgeTemp" value="5"/></td>
</tr>
<tr>
<td>Freezer Temperature:</td>
<td><input type="text" name="freezerTemp" value="-30"/></td>
</tr>
<tr>
<td colspan="2">
<input type="Submit" value="Set temperature"/>
</td>
</tr>
</table>
</form>
|
GET tells the resource to dynamically create HTML and return it to the
browser.
POST tells the resource that the user wants to set new
data.
If the user wants to change the temperature, the user can use the form displayed in the browser to change the values and then press the submit button. When the user presses the submit button, the browser collects the data in the form and sends it as URL-encoded data to the server. The Barracuda server decodes the URL-encoded data and starts the resource specified in the POST command. In Barracuda, this will typically be the same resource as the resource that produced the initial HTML page. A naive web-server forces the web-developer to POST the data to a predefined fixed URL, for example, a CGI Web Server forces the web-developer to POST data to the "cgi/" directory.
A Barracuda resource is typically derived from the HttpPage type. When the user requests a resource, the Barracuda Web Server locates the resource and delegates the request to the resource. A resource gets two objects from the server, a request object and a response object. The request object contains information about the client and any data sent from the client. The response object is used when dynamically creating the response data, such as an HTML response.
The following shows a code fragment from a resource object serving a HTTP GET request.
As you can see from the above fragment, the resource object creates a simple HTML page containing a greeting message.
Most Web-Developers want to separate content from logic. The above HttpPage resource code example shows a tight integration of code and HTML content. Maintaining such a resource is difficult and time consuming. The HttpPage resource makes it possible to do advanced HTTP communication. A way of separating logic and content, while giving developers the flexibility of the services provided by a HttpPage resource is needed.
The Barracuda platform solves this problem by providing a special TAG compiler that takes an HTML file and translates the file to an HttpPage. The TAG language is called CSP. CSP, short for C Server Pages, is a modern reimplementation of the CGI standard. CSP extends HTML with new tags that are only visible on the server side.
The following shows a very simple CSP page.
The above example shows that a CSP page looks like a regular HTML file. This page contains no special CSP tags and behaves like static HTML file.
CSP also makes it easy to create dynamic pages. A dynamic page is a resource that creates content either from user input or from some information in the device.
Let us now change the above simple CSP page to the following:
CSP tags start with <% and end with %>. The <%= tag tells the CSP runtime to take the following string and send it to the client that requested the resource -- i.e. to the browser.
We have now added a CSP tag to the page, but the result produced is identical to our first CSP page. The string "Greetings" is constant and will never change.
Continuing with our CSP example page:
Now we added some C++ code directly into the HTML page. The method getHeaderValue in the request object returns the value for the "User-Agent" HTTP request header value. The Barracuda server decodes all the header values and keeps them in an internal table, thus getHeaderValue("User-Agent") returns the identity of the client doing the request.
Barracuda is a C library written in ANSI C compatible code, but provides both a C++ and a C interface. The above C++ code can be written as the following C code
The Barracuda framework provides a rich API to the developer. A CSP resource can use all of the C or C++ methods provided by this API. A CSP resource has two implicit objects available when executing: the request and response object. The request object provides information sent from the client to the server, while the response object is used when sending data back to the client. The response object is implicitly used in the above code by the <%= tag.
The first phase of developing a CSP application is creating the HTML interface, and is usually handled by a professional web interface developer. The second phase involves a C programmer or web developer with a small amount of C experience to add the CSP tags to the HTML code.
The final step is testing the new interface in the Barracuda Embedded Web Server. This can be an iterative process, and will show places where adjustments should be made to the HTML or other interface components. HTML editors such as Dreamweaver will not corrupt or remove the CSP tags with the C/C++ code.
The following examples are simple so that they can easily be understood. In most web applications, the HTML would be much more extensive, and would also likely involve CSS.
First, we'll add an interface to display the temperature reported by a new controller unit on our refrigerator.
The <%= tag by default assumes that the data is a string. All other types must be explicitly declared. The <%= tag accepts the same format flags as printf, so <%="%d" means "print an integer value". The above code uses the ANSI C function rand to generate a random temperature value. A real implementation would call a function that returns the actual temperature. The modulus operator is used such that we get a refrigerator temperature between 0 and 10 degrees Celsius, and a freezer temperature between 0 and -35 degrees Celsius.
Most of the content in this example page is static. This is typical when working with CSP. The HTML framework is always the same, but the temperature data is dynamically presented to the user.
An improvement to this, which just prints out the temperature of the freezer and refrigerator in an HTML table, would be to present the temperature graphically as a bar chart.
|
There are a number of ways to create a bar chart using HTML. This example will dynamically create a HTML table containing small images. The figure to the right shows a bar chart representation of a freezer temperature of -25 degrees Celsius and a refrigerator temperature of 4 degrees Celsius: Show table frame |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
The colors blue, green, yellow, orange and red are used. Also, a transparent image is used when hiding the temperature element. The above freezer bar contains 5 transparent images for the temperature -20, -15, -5 and 0.
To keep the example as simple as possible, the refrigerator temperature is not included in our CSP example. The table in the CSP code below contains three table row elements (<tr>). The first row contains a table data element, which spans across 8 elements, the second row contains the temperatures, and the last table row contains the images. The getFreezerImg function returns the string for the current image to insert into the table element.
The above example demonstrated several new tags.
The <%g tag means global. Anything declared here goes outside of the generated HttpPage. The getFreezerImg function is inserted into the global area by the CSP compiler.
The <%p is the prolog tag. Anything declared here is inserted at the beginning of the HttpPage service function. The <%p is a special form of a code fragment tag.
The <% is a code fragment tag. Anything in a code fragment tag is executed when the HttpPage service function runs. For example, the following code fragment tag from the example above prints out table data elements containing the images.
The following will be printed out by the above code fragment if the freezer temperature is -25 degrees:
We use the printf function in the response object to print out the table data elements. Another possibility is shown below.
This produces the same output as the original code fragment.
A client application does not necessarily have to be a web-browser. When a browser sends data to a server, the content type of the data normally is "application/x-www-form-urlencoded". Browsers don't normally send other content types without executing JavaScript code.
URL-encoded data is sent as key/value pairs as "key1=value1&key2=value2&key3=value3".
Some characters must also be "quoted" to prevent them from being handled as control characters. This "quoting" is transparent to the CSP designer when using the Barracuda framework.
Sending data from a browser to the server normally works like this:
The following code will make the refrigerator resource also able to change the temperature settings.
If you look at the HTML section, you will see that we have now added a HTML form element to the page. The original table data elements printing out the temperature are now changed to a table data element containing a HTML form input type.
The default value for fridgeTemp is 5 degrees, so what is initially sent to the browser is:
When the user clicks the submit button, the browser sends the data to the web-server. The initial HTTP POST command in the HTTP section above shows what this form data looks like during transmission. The URL-encoded data "fridgeTemp=5&freezerTemp=-30" corresponds to the two field names in the CSP example.
The CSP code extracts the fridgeTemp and freezerTemp in the prolog section, i.e., the tag starting with <%p.
The code example above uses the keys "fridgeTemp" and "freezerTemp" in order to fetch the value part of the data.
The server will perform a sanity check on the data. This is an important step and is typically where web applications fail. If the sanity check fails, the user is forwarded to a page explaining food safety. This is something we added for fun. A web application would normally respond with an error page.
Another implicit sanity check is performed by the U32_atoi function. The U32 is an unsigned 32 bit type in the Barracuda web-server. The U32_atoi function works like the standard atoi function, but it also can tolerate a NULL string without crashing. Even though the U32 function returns an unsigned integer, the function can decode and negate negative numbers.
Hackers are constantly trying to penetrate and crash web servers by using a number of methods, and they aren't connecting to web servers with browsers for these attacks. They won't always be sending proper form data, so the server must check that all required fields are present.
There are a lot of buzzwords on the internet these days about Rich Client applications, like "Rich Client Interface", "DHTML client", "Web Services", "Ajax", etc. A Rich Client application uses the browser as an environment to create a fully interactive graphical user interface rich and interactive user interface, and lies between a standard lightweight HTML form and a full native client-side OS-based application. A Rich Client can also be a standard Windows application that communicates with the server using HTTP, althoug such an application must be installed on the host computer before interacting with the server.
Modern browsers natively support a programming language called JavaScript. They also have a standard API, the Document Object Model, that JavaScript code can use for creating the user interface. This API allows the JavaScript code to create interactive GUI applications that resemble native applications. This basically means that you can design Dynamic Web-Applications using DHTML without the need of refreshing or reloading pages when you send data to the server.
A DHTML client communicates with the server using an object called XMLHttpRequest which, despite the name, has nothing to do with XML. The XMLHttpRequest allows JavaScript code to send any type of HTTP request to the server.
Below we have created a Rich Client Interface for the simple fridge controller we discussed above.
The popular "Web Services" is basically a method of serializing and de-serializing objects over HTTP. Barracuda supports XML-RPC Web Services, even a standard Web Services client can be used when communicating with Barracuda. Typically, Web Services won't be used in a DHTML client when URL encoded data is sufficient. The original resource already accepts URL encoded data which is much easier to manage for most applications.
The resource "/refrigerator/temperature/ex4.html" is designed to accept URL encoded data. Our original resource wasn't configured to handle Web Services requests, so a new temperature object should be constructed specifically for Web-Services.
The response from the XMLHttpRequest object is sent asynchronously to a JavaScript callback function. The original service function responds by sending a HTML page to the client. A DHTML client could potentially parse the HTML to get the new temperature settings, but this requires a lot of work. A better solution is to tell the server resource that the client accepts JavaScript code as a response message by setting the correct "Accept" header in the request.
The server resource can simply check for this header.
If the client sent the header, then a JavaScript object is sent as response message.
Ajax is an example of this, and can be found by searching on the internet. You can also take a look at Google Suggest, which is using an XMLHttpRequest object in the background as you type your search string.
