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.
- 1 Web Server Interface
- 1.1 User Interface
- 1.2 Event Interface
- 1.3 Common Gateway Interface (CGI)
- 1.4 Server Side Include (SSI) Interface
- 1.5 Accessing Request Information
- 1.6 Accessing Request Body
- 1.7 Low-Level response API interface
- 1.8 Using SSL with the Treck Web Server
- 2 File System Interface
- 3 ROM FS Builder
- 4 Function References
- 5 Examples
Web Server Interface
The user interface allows the user to start/stop HTTP servers and configure the authentication information.
Specify the maximum number of web servers the user plans to run.
Allows the user to set initialization-time options for the web server
Set run-time options for the web server.
- 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
The user calls tfHttpdUserStop() to kill all existing HTTP connections and close the HTTP server socket.
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.
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() 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.
- 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.
- 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.
- 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() closes an HTTP connection.
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()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() sets the SSI file filter. The web server uses the filters to determine whether a file needs to be parsed for SSI tags.
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() sends the HTTP response status line.
tfHttpdUserSendResponseHeaders() sends the HTTP response headers.
tfHttpdUserSendResponseBody() sends the HTTP response body.
Using SSL with the Treck Web Server
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:||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.
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:||To use the ROM file system, you need to define TM_USE_ROM_FS|
Web Server Application Example Code
Start the web server
|examples/httpd/txcgi.c||Example CGI handler for testing|
|examples/httpd/txssi.c||Example SSI handler for testing|