Web Server

Jump to: navigation, search

Table of Contents >> Application Reference

Web Server is an efficient and easy way to access and manage an embedded system through a standard web browser interface. Treck Web Server runs in either blocking mode with RTOS support or non-blocking mode without any RTOS. HTTP1.1 multiple connection and pipeline request are supported. CGI is supported for generation of dynamic HTML using HTTP1.1 chunked encoding. ROM file system interface and ROM file image building tool are provided.

Web Server Interface

User Interface

The user interface allows the user to start/stop HTTP servers and configure the authentication information.

tfHttpdUserInit()

Specify the maximum number of web servers the user plans to run.

tfHttpdUserInitOptions()

Allows the user to set initialization-time options for the web server

tfHttpdUserSetOptions()

Set run-time options for the web server.

tfHttpdUserStart()

The user calls tfHttpdUserStart() to open a HTTP socket and start listening for incoming connections. tfHttpdUserStart() can be either blocking or non-blocking as specified by its last parameter.

  • Blocking Mode
    In blocking mode, tfHttpdUserExecute() should be called from a task, and will not return unless an error occurs. It will block and wait for incoming connections, and execute the HTTP server code in the context of the calling task. Choose blocking mode if you are using a RTOS/Kernel.
  • Non-Blocking Mode
    In non-blocking mode, tfHttpdUserExecute() will return immediately after listening for incoming connections. It is the user’s responsibility to then call tfHttpdUserExecute() periodically to execute the HTTP server code. Choose non-blocking mode if you do not have a RTOS/Kernel.

tfHttpdUserStop()

The user calls tfHttpdUserStop() to kill all existing HTTP connections and close the HTTP server socket.

tfHttpdUserAuthConfig()

The user calls tfHttpdUserAuthConfig() to configure HTTP authentication information. Basic and Digest authentication are supported (RFC 2617).

tfHttpdUserExecute()

In blocking mode, the user needs to call tfHttpdUserExecute() once, tfHttpdUserExecute() will block unless an error occurs. In non-blocking mode, the user needs to call tfHttpdUserExecute() periodically.

Event Interface

The user needs to implement an interface to handle the events the webserver has generated. Through the event interface, logging and CGI are supported. To get the events, user needs to register an event handler by calling tfHttpdUserSetEventHandler().

Common Gateway Interface (CGI)

The HTTP server supports CGI, which allows the user to dynamically generate server responses. To handle CGI requests, the user needs to process the TM_HTTPD_EVENT_SEND_READY event, when the web server calls the user supplied event handler, to signal the user to send data, or when there is more room to send additional data to serve a previous request. Users should try and send a CGI response by calling tfHttpdUserSendBuffer().

tfHttpdUserSendBuffer()

tfHttpdUserSendBuffer() is used to send out a user buffer to the HTTP client through the HTTP connection. It can be called multiple times to aggregate a large page. Three OR’able flags can be passed in, TM_BLOCKING_ON, TM_HTTPD_FLUSH, and TM_HTTPD_END.

  • TM_BLOCKING_ON
    If this flag is set, this function is blocking, and it is recommended that the user calls tfHttpdUserSendBuffer() in a different thread. Otherwise, the function is non-blocking. Return value TM_SOCKET_ERROR with errorCode TM_EWOULDBLOCK could be returned if there is no more room in stack to send the buffer. In that case, the web server will signal another TM_HTTPD_EVENT_SEND_READY event later.
  • TM_HTTPD_FLUSH
    By default, when calling tfHttpdUserSendBuffer(), the data will not be transmitted until the web server has been given enough to fill a full-size packet. Setting this flag will force the server to immediately transmit all unsent data.
  • TM_HTTPD_END
    The user sets this flag to tell the web server that the CGI request has been completely served. The web server will not generate any more TM_HTTPD_EVENT_SEND_READY event for this CGI request. The user could also use this flag to indicate that it doesn’t want to serve a CGI request when it receives the TM_HTTPD_EVENT_SEND_READY event.

tfHttpdUserClose()

tfHttpdUserClose() closes an HTTP connection.

tfHttpdUserGetConInfo()

tfHttpdUserGetConInfo() gets connection and CGI request information.

Server Side Include (SSI) Interface

SSI commands are special HTML comment tags placed in web pages, and parsed by the web server while the pages are being served. They allow dynamically generated content to be inserted into a static page, without having to dynamically generate the entire page. There is no official standard for SSI command. Each web server implementation can define its own SSI syntax. However, most of the server implementations support a standard set of SSI commands. Currently, Treck Web server SSI option doesn’t implements any of the standard SSI tags. We provided an API for the user to register a SSI tag string and a handler function. When a registered SSI tag is found in a page being served, the handler function will be called to process it.

Three APIs are provided for SSI operations.

tfSetTreckOptions()

tfSetTreckOptions()To be called with TM_OPTION_SSI_MAX_TAG_LEN to choose the maximum SSI tag instance length that could appear in any SSI page. This is to optimize the performance of the SSI parser. The default value is 256.

tfHttpdUserSetSsiFileFilter()

tfHttpdUserSetSsiFileFilter() sets the SSI file filter. The web server uses the filters to determine whether a file needs to be parsed for SSI tags.

tfHttpdUserRegisterSsiTag()

tfHttpdUserRegisterSsiTag() registers an SSI tag string and the associated handler. The user must implement the SSI handler. Function type is defined as ttHttpdUserSsiHandler.

Accessing Request Information

The request method line and headers information can be accessed through the user connection entry by calling tfHttpdUserGetConInfo.

Accessing Request Body

Normally, the web server handles most POST request body automatically without the user’s application. In these cases, the web server simply parse through the request body to collect form elements and present them as CGI arguments to the user. In some other cases, the user might be interested in directly accessing the request message body to perform application specific options. The user can do so by calling tfHttpdUserGetRequestBody. Note that, even if the user is not interested in the request body, he still needs to call this API to consume the request body when an event TM_HTTPD_EVENT_BODY_RECV is received, user can set the TM_HTTPD_DISCARD flag to tell the web server to discard the received body.

Low-Level response API interface

The following APIs provides a low-level user interface that allows the user to send a fully customized HTTP response message with the specified HTTP elements. This includes send a status line with the specified HTTP version, and status code, a appropriate reason phrase will be added automatically; user specified header types and values; and user specified body message. The user sent response message overrides the automatic response usually generated by the server.

tfHttpdUserSendResponseStatusLine()

tfHttpdUserSendResponseStatusLine() sends the HTTP response status line.

tfHttpdUserSendResponseHeaders()

tfHttpdUserSendResponseHeaders() sends the HTTP response headers.

tfHttpdUserSendResponseBody()

tfHttpdUserSendResponseBody() sends the HTTP response body.

Using SSL with the Treck Web Server

The Treck Web Server may be used with Treck's SSL implementation. To do so tfHttpdUserSetSsl() must be called to enable SSL.

Example of using the Treck Web Server with SSL

    errorCode = tfHttpdUserInit(...);
...
    serverHandle = tfHttpdUserStart(...);
...
#ifdef TM_USE_SSL_SERVER
    errorCode = tfUsePki();
...
/* the following user provided function adds CA's certificate by
calling tfPkiCertificateAdd, server's private key by calling
tfPkiOwnKeyPairAdd, and server's certificate by calling
tfPkiCertificateAdd. */
    errorCode = myTestAddServerKeyAndCertificate();
...
    errorCode = tfUseSsl(...); /* maximum sessions */
...
    sessionId = tfSslNewSession(...);
...
    errorCode = tfHttpdUserSetSsl(serverHandle,
                                    sessionId);
/* optional. User may call tfHttpdUserSetSockopt directly to change SSL
option value, such as TM_TCP_SSL_SEND_MIN_SIZE , TM_TCP_SSL_SEND_MAX
_SIZE, TM_TCP_SSLSESSION or TM_TCP_SSL_SERVER.
*/
    errorCode = tfHttpdUserSetSockopt(...);
#endif /* TM_USE_SSL_SERVER */
    tfHttpdUserExecute(serverHandle);

File System Interface

The Treck Stack works with a generic file system interface that can be mapped to any real file system. With the stack, we provide four example file systems that we have either implemented or ported to. They are ready to be used by the web server by defining the respective macros in <trsystem.h>. If you would like to use a file system of your own that you have ported under the Treck file system interface, please do not define any of the three existing file system enabling macros.

Note Note: Only one file system can be enabled at a time.


File system name Enabling macro Description
Treck ROM file system TM_USE_ROM_FS Implemented in <\source\trromfs.c>. This is the Treck ROM file system implementation. It supports multiple memory pages/segments. The Treck ROM file system works with the ROM FS builder which is explained in

the ROM FS Builder section below.

Treck RAM file system TM_USE_RAM_FS Implemented in <\source\trramfs.c>. This is the Treck RAM file system implementation.
DOS file system port TM_USE_DOS_FS This is a port to DOS/Windows file system, mainly for prototyping and testing purpose. The Treck file interface functions are mapped to the real DOS file system function calls.

For security reasons, we need to restrict the access to the DOS file system to be under a certain directory only. By default, it is set to the current working directory that the application was started.

UNIX emulating DOS file system port TM_USE_EMU_UNIX_FS This is a port to DOS/Windows file system that emulates UNIX, mainly for prototyping and testing purpose. The Treck file interface functions are mapped to the real DOS file system function calls but the input/output emulates a UNIX file system.

ROM FS Builder

Treck ROM FS Builder, located under <\treckbin\trromfs\trromfs.exe>, is a Windows based GUI tool. It allows the user to build a ROM file system image from the files under a Windows directory and its sub-directories. The generated image is one .h file, and one or more .c files. Under the Treck source tree, you will find them as <\include\trrombld.h> and <\examples\romfs\txrom0.c>, <txrom1.c> ... <txromn.c>. <\source\trromfs> includes the <\include\trrombld.h> file so that it knows the structure of this ROM file system image. The actual file contents are located in the generated .c files. An important feature is to support multiple ROM pages/segments. The page size can be specified in the UI.

Function References

Examples

ROM FS Image

We have built a simple ROM FS image as an example. The web pages used to create the ROM image is located under treckbin\trromfs\demopage\. The resulting ROM FS image is <trrombld.h> located under the include directory and several .c files under examples\romfs. To use this example image, you’ll need to link the .c files into your executable. <trrombld.h> will be automatically included by <trromfs.c>.


Note Note: To use the ROM file system, you need to define TM_USE_ROM_FS

Web Server Application Example Code

File name Contents
examples/httpd/txhttpd.c

Start the web server
Set the max SSI tag length
Configure the SSI file filter
Register the SSI tag

examples/httpd/txcgi.c Example CGI handler for testing
examples/httpd/txssi.c Example SSI handler for testing
treckbin/trromfs/demopage/* Test pages


Table of Contents >> Application Reference