Creating Web-Based Applications Using ATL Server

In this section, we’ll look at the first type of project you can build with ATL Server: Web-based applications. First I’ll give you an overview of the server architecture, and then you’ll see how to build a sample application.

ATL Server Architecture

The architecture of ATL Server applications is shown in the following illustration:

click to expand

There is one ATL Server ISAPI DLL per Web server; it acts as an extension to IIS, forwarding requests to the Web-based applications.

Browser clients use the URL of a Server Response File (SRF) to connect to the server. SRFs define the layout of the page and how the methods exposed by ATL Server will be used. The ISAPI DLL is registered as the default handler for SRFs, so it processes the file, making use of ATL Server to provide dynamic content. See the following exercise for details about what an SRF looks like.

SRFs are similar to ASP pages; they contain a mixture of HTML and references to functionality within the ATL server. The tags—within double braces ({{}})— are called replacement tags. As with ASP pages, the dynamic content is separated from the static layout.

SRFs typically contain three types of information:

  • The name of the handler class and the DLL it lives in

  • Static HTML for the returned page

  • Placeholder tags in the HTML, which are replaced with dynamic content at run time

Here’s a very simple SRF:

{{handler mydll.dll/Default}} <html><body> {{aCommand}} </body></html>

The placeholders are enclosed in double braces because, as far as HTML is concerned, they are plain text. They won’t be treated specially by intelligent tools such as Microsoft FrontPage.

SRFs are processed by the stencil processor code that is part of ATL Server. Once SRFs have been parsed by the processor, they are cached so they can be used again without need for additional parsing. If the text in the SRF file changes, it is reparsed the next time it is used.

The stencil processor loads the handler DLL specified in the {{handler}} placeholder and looks for the handler class whose name is specified after the slash. A single ATL Server DLL can contain many handler classes, one of which can be identified as the Default handler. The ATL Server DLL also contains a handler map that links handler names to ATL classes within the DLL. Here’s a typical handler map:


The map associates class names with the handler names that are used in the SRFs.

Here’s a simple definition of a handler class:

[request_handler("Default")] class CMyHandler { public: HTTP_CODE ValidateAndExchange(); [tag_name="aCommand"] HTTP_CODE OnCommand(); };

This is the simplest way to set up a handler class. If you want more of a challenge, you can do it the traditional ATL way by manually deriving a handler class from the requisite ATL base classes (in this case, CRequestHandlerT<>), but attributes make life a lot easier in Visual C++ .NET.

The request_handler attribute marks this class as a handler and establishes its name. Methods within the class can be tagged with a tag_name attribute that matches a method with a name used in a placeholder tag in an SRF.

The ValidateAndExchange method is used to validate any parameters passed in through HTTP and to perform any initialization needed by the handler. The HTTP_CODE return type is used to return an HTTP status code; it tells the caller whether the call worked.

More About Server Response Files

Putting a tag name in an SRF file results in the corresponding method being called. There are also some other commands that let you do more complex processing.

The {{include}} command lets you refer to another SRF, which the processor will load and parse. The {{if}}, {{else}}, and {{endif}} tags let you perform conditional processing, calling a command that returns HTTP_SUCCESS or HTTP_S_FALSE to denote logical true or false values. This means you can put text like this within an SRF:

{{if CardNumberIsValid}} <p>Card validated. {{else}} <p>Card number invalid. {{endif}}

If the CardNumberIsValid handler returns HTTP_SUCCESS, the text <p>Card validated. is echoed to the response stream; if the handler returns HTTP_S_FALSE, <p>Card number invalid. is echoed. Here’s the code for the method:

HTTP_CODE CardNumberIsValid() { HTTP_CODE retval = HTTP_S_FALSE; LPCSTR pszNumberToCheck = m_HttpRequest.m_pFormVars->Lookup("CardNumber"); if (pszNumberToCheck && pszNumberToCheck[0]) { // check the number if (ok) retval = HTTP_SUCCESS; } return retval; }

The code assumes that the calling form contains an input field called CardNumber. It then retrieves the content of the field from the HTTP header using the m_HttpRequest object that represents the HTTP request stream. If you need to write HTML output back to the client, you can use the Write method of the m_HttpResponse object.

The value returned by the function determines what HTML is included in the response.

Writing a Web Application Using ATL Server

The following exercise shows you how to create a Web application using ATL Server.


NoteAs with the projects in Chapter 23, when you install and run Web application projects you must have IIS installed on your machine.

  1. On the File menu, select New and then Project to open the New Project dialog box.

  2. Expand the Visual C++ Projects folder in the left pane, and select the ATL subfolder. Click ATL Server Project in the right pane. Call the project MyAtlServer.

    click to expand

  3. Click OK to bring up the ATL Server Project Wizard.

    click to expand

    The ATL Server Project Wizard has several pages; the illustration shows the Application Options page. Although there are a number of options you can customize, for this simple example you can accept all the default settings. For details about some of the other options available through the wizard, see the following sidebar, “ATL Server Project Options.”

    start sidebar
    ATL Server Project Options

    The ATL Server Project Wizard has four pages of options: Project Settings, Server Options, Application Options, and Developer Support Options.

    The Project Settings page lets you choose whether to create separate or combined DLLs. ATL Server is an ISAPI extension for a Web server, so it has both an ISAPI part and an ATL part. These can be created as two separate DLLs or combined into one. The other major option on this page allows you to select deployment support, which means your project is automatically deployed to the server.

    The Server Options page lets you set various support options, such as adding performance counters and data caching support, and it also lets you set up session state services so you can persist data across requests to the service.

    Nothing on the Application Options page applies to Web service projects, but the Developer Support Options page lets you set three options that help you work with the project: adding TODO comments, adding debug support so the service can be debugged using the WebDbg utility, and specifying whether attributes are used in the generated Visual C++ code.

    end sidebar

  4. Click Finish to create the project files.

    You’ll find that two projects have been created for you in two separate directories: MyAtlServer for the ATL Server files and MyAtlServerIsapi for the ISAPI extension files.

  5. The ATL Server project already contains a sample function that returns a “Hello World” string. Add another method that will return the current date and time as a string. Start by adding the include file for the C++ date and time functionality to the top of the MyAtlServer.h file after the #pragma directive, as shown here:

    #pragma once #include <ctime> 

    This code includes the standard ctime header file, which in standard C++ simply includes the old C time.h header.

  6. Add the new method to the CMyAtlServerHandler class with the following code:

    // A replacement tag to return the time [ tag_name(name="GetDate") ] HTTP_CODE OnGetDate(void) { time_t theTime; time(&theTime); tm* loctm = localtime(&theTime); m_HttpResponse << asctime(loctm); return HTTP_SUCCESS; }

    The function gets the current time and stores it into a time_t variable, and then it uses the localtime function to convert to the local time zone. The asctime function is used to render the local time as a string, which is passed back to the m_HttpResponse object.

    Note that tag_name is set to GetDate, which is how you refer to this command in the SRF file.

  7. Edit the SRF file to use the new command. Open the MyAtlServer.srf file in Visual Studio .NET, and be sure to use the tabs at the bottom of the code window to change to HTML view. Edit the SRF code so it looks like this:

    <html><HEAD></HEAD> <BODY> {{// A simple SRF file}} {{handler MyAtlServer.dll/Default}} <h2>Time Server</h2> The current date and time is: {{GetDate}} </BODY> </html>

    The {{// ...}} line is an SRF comment; you can use as many as you like to document your SRF files. The {{handler}} command establishes the DLL and handler to be used for this SRF file, and the {{GetDate}} command calls the function in the DLL whose output will be merged with the fixed content.

  8. Build the project. This results in both ATL and ISAPI DLLs being built and deployed to the Web server. If you look in the output window, you should see something like this:

    ------ Build started: Project: MyAtlServer, Configuration: Debug Win32 ------ Compiling... StdAfx.cpp Compiling... MyAtlServer.cpp Linking... Creating library Debug/MyAtlServer.lib and object Debug/MyAtlServer.exp Deploying the web files... Copied file from c:\MyAtlServer\MyAtlServer.srf to c:\inetpub\wwwroot\MyAtlServer\MyAtlServer.srf Copied file from c:\MyAtlServer\Debug\MyAtlServer.dll to c:\inetpub\wwwroot\MyAtlServer\MyAtlServer.dll Build log was saved at "file://c:\MyAtlServer\Debug\BuildLog.htm" MyAtlServer - 0 error(s), 0 warning(s) ------ Build started: Project: MyAtlServerIsapi, Configuration: Debug Win32 ------ Compiling... StdAfx.cpp Compiling... MyAtlServerIsapi.cpp Compiling resources... Linking... Creating library Debug/MyAtlServerIsapi.lib and object Debug/MyAtlServerIsapi.exp Deploying the web files... stopping W3SVC...... starting W3SVC.................................................. Copied file from c:\MyAtlServerIsapi\Debug\MyAtlServerIsapi.dll to c:\inetpub\wwwroot\MyAtlServer\MyAtlServerIsapi.dll Build log was saved at "file://c:\MyAtlServerIsapi\Debug\BuildLog.htm" MyAtlServerIsapi - 0 error(s), 0 warning(s)

    Both projects are built, and the requisite files are copied to the correct virtual directory on the server. Note how the Web server is stopped and restarted when the ISAPI DLL is installed, just in case the DLL is already in use.

Using the Web Application from a Browser

The application can be used easily from a browser: you simply enter the URL of the SRF file into the browser’s Address field. In this case, the URL is http://localhost/MyAtlServer/MyAtlServer.srf. When the SRF file has been processed, you’ll see the output in the browser window:

click to expand

Microsoft Visual C++  .NET(c) Step by Step
Microsoft Visual C++ .NET(c) Step by Step
ISBN: 735615675
Year: 2003
Pages: 208 © 2008-2017.
If you may any questions please contact us: