C Server Pages, CSP

CSP makes it possible to embed C and C++ code in a standard HTML file. The C and C++ code embedded in HTML can communicate directly with your application, hardware, or both.

The CSP compiler is designed to run on a host computer and is usually invoked from a makefile. Most Barracuda example makefiles use the CSP compiler and linker. The CSP compiler translates a CSP file into a C/C++ file containing one HttpPage. A CSP file is therefore a convenient way to create an extended HttpPage. The generated source file is compiled to object code by your target C or C++ compiler.

The CSP compiler lets a web designer create the HTML framework for a page without knowing C or C++. A C or C++ programmer can then add the dynamic content. If the HTML framework changes later, the designer can continue using standard HTML tools. These tools normally preserve unknown tags, so the embedded C or C++ sections are not altered.

The CSP model is similar to Microsoft's Active Server Pages (ASP), so ASP programmers should find the scripting model familiar.

An HttpPage is comparable to a Java Servlet. The CSP compiler translates a CSP file into an HttpPage. When a client requests a page, the web server looks up the page in the Virtual File System. When the page is found, the web server calls the page service function generated by the CSP compiler.

This CSP code contains only static HTML elements, and the request object passed as argument to the service function is not used by this CSP HTML code. The HttpPage generated for this example writes the static HTML to the response object, but the example only illustrates how a CSP page conceptually works. The actual HTML code is not emitted as shown above, but is fetched from a cspPages.dat file generated by the CspLink tool, which will be explained later.

Although this static HTML example works, the CSP technology's strength is in web applications that serve dynamic content.

CSP pages typically comprise:

Static HTML/XML components
Special CSP tags
Snippets of code written in C or C++ code

You can thus create and maintain CSP pages by conventional HTML/XML tools. Here is an example of a simple Web-Counter script that can be compiled by CspCompile:

<%! int myCount; %>
<%!! this->myCount = 0; %>
<HTML>
<BODY>
<P> This web page has been visited
<%HttpResponse_printf(response, "%d ",this->myCount++);%>
number of times </P>
</BODY>
</HTML>

The CspCompiler recognizes the <% tag as the start of an embedded C/C++ code section and the %> tag as the end of that section.

The CspCompiler can also generate C++ code, so the script can be written as:

<%! int myCount; %>
<%!! myCount = 0; %>
<HTML>
<BODY>
<P> This web page has been visited
<%response->printf("%d ",myCount++);%>
number of times </P>
</BODY>
</HTML>

The two examples above can also be written in either C or C++ as:

<%! int myCount; %>
<%!! this->myCount = 0; %>
<HTML>
<BODY>
<P>
This web page has been visited<%="%d" this->myCount++%>number of times </P>
</BODY>
</HTML>

A web application typically consists of dynamically generated pages (CSP) and static content such as GIF images, style sheets, JavaScript files, and other resources. The CspCompiler can compile static content, but this is inefficient because an HttpPage is generated for each resource. A better approach is to store static content in a ZIP file and serve it through HttpResRdr and ZipIo. Together, HttpResRdr and ZipIo expose the ZIP file as a read-only file system. If a ZIP-backed directory and a CSP-backed directory have the same name, the Virtual File System combines them so the client sees one directory branch.

The Web Server also includes a tool that simplifies the integration of dynamic and static HTML into your system. The CspMakeGen Lua script can be used for generating a makefile for your HTML. The tool can recursively traverse a directory containing HTML files. The tool will generate a makefile dependency for all .html and .shtml found in the directory and subdirectories.

This section is a quick introduction to CSP. ASP and JSP programmers should be able to map the concepts to familiar server-side page models.

CSP tags

The CspCompiler recognizes seven tags.

The CSP tags:

<%g %>	Global declarations, such as #include directives and type declarations.
<%! %>	Declarations. An `HttpPage` object can add its own data members. Variables declared here are initialized with the <%!! %> tag.
<%!! %>	Initialization. The `HttpPage` constructor code goes here. This code is called once when the application starts and should initialize variables declared with the <%! %> tag.
<%p %>	Prologue code. Code placed here is emitted at the top of `HttpPage_service`, the CSP service function. This tag is especially useful in C because it lets you declare variables in the service-function scope.
<%e %>	Epilogue code. Cleanup code that runs just before `HttpPage_service` returns. The compiler emits a label just before the epilogue code. Generated code jumps to this label if an execution error is detected. Application code can also jump to this label to centralize cleanup. Example: `if(error) goto L_epilogue;`
<% %>	Code fragments. A code fragment can contain any number of language statements, variable declarations, or expressions that are valid in the page scripting language, which is C or C++.
<%= %>	The expression tag. Format flags are the same as those used by `printf`. If no format flag is specified, the expression is treated as a string. These two tags produce the same result: <%="hello"%> <%="%s" "hello"%>. You can also print more complex expressions. For example: <%="%s %d %s" "Hi, I am", 10, "years old"%>.

HttpPage Service Function

The HttpPage class contains a page service function, which is executed by the Virtual File System when the resource is accessed by a client. This function is similar to the servlet service function in a Java HTTP Servlet application server.

When a user requests http://myServer/dir1/dir2/myPage.html, the Web Server traverses the Virtual File System from root to dir1 and then to dir2. The dir2 HttpDir instance locates myPage.html and calls the page service function.

HttpPage is an abstract class that must be extended:

C header file example:

struct MyPage
{
  HttpPage super; /* As if inherited */
  int myCount;
};

C++ header file example:

class MyPage : public HttpPage
{
  int myCount;
};

The page object must provide two functions: a constructor and the service function.

C code example:

static void
MyPage_service(struct HttpPage* page,
               HttpRequest* request,
               HttpResponse* response)
{
  MyPage* o = (MyPage*)page; /* Cast to my object */
  HttpResponse_printf(response, "<html><body>");
  HttpResponse_printf(response,
                   "<p>This web page has been visited %d number of times</p>",
                   o->myCount);
  HttpResponse_printf(response, "</body></html>");
}

void
MyPage_constructor(MyPage* o)
{
   HttpPage_constructor(&o->super, MyPage_service, "MyPage");
   o->myCount = 0;
}

The CspCompiler generates the required HttpPage code for CSP pages. Using CspCompiler is usually much easier than writing the HttpPage service function manually. A manually written service function is best reserved for pages with little or no static HTML.

See CSP Tools for more information about CspCompiler and the tools required for compiling CSP pages.

Hidden Files

Server Side Include files should not be confused with server-side scripting. They are special files that are hidden from regular browser requests. These files should use the .shtml extension. The CspCompiler treats .shtml files as resources that can only be accessed through HttpResponse::include and HttpResponse::forward. A direct browser request returns "404 not found".