Wrapping ISAPI

You now have a simple extension written directly to ISAPI, but programming against raw ISAPI is rather awkward. It sure would be nice to have some more object-oriented wrappers. Luckily, ATL Server provides exactly that. The CServerContext class is a COM object that provides a wrapper around the ECB.

class CServerContext :                                       
    public CComObjectRootEx<CComMultiThreadModel>,           
    public IHttpServerContext {                              
public:                                                      
    BEGIN_COM_MAP(CServerContext)                            
        COM_INTERFACE_ENTRY(IHttpServerContext)              
    END_COM_MAP()                                            
                                                             
    void Initialize(__in EXTENSION_CONTROL_BLOCK *pECB);     
                                                             
    LPCSTR GetRequestMethod();                               
    LPCSTR GetQueryString();                                 
    LPCSTR GetPathInfo();                                    
    LPCSTR GetScriptPathTranslated();                        
    LPCSTR GetPathTranslated();                              
    DWORD GetTotalBytes();                                   
    DWORD GetAvailableBytes();                               
    BYTE *GetAvailableData();                                
    LPCSTR GetContentType();                                 
    BOOL GetServerVariable(                                  
        LPCSTR pszVariableName,                              
        LPSTR pvBuffer,                                      
        DWORD *pdwSize);                                     
                                                             
    BOOL WriteClient(void *pvBuffer, DWORD *pdwBytes);       
    BOOL AsyncWriteClient(void *pvBuffer, DWORD *pdwBytes);  
    BOOL ReadClient(void *pvBuffer, DWORD *pdwSize);         
    BOOL AsyncReadClient(void *pvBuffer, DWORD *pdwSize);    
                                                             
    BOOL SendRedirectResponse(__in LPCSTR pszRedirectUrl);   
    BOOL GetImpersonationToken(__out HANDLE * pToken);       
                                                             
    BOOL SendResponseHeader(                                 
        LPCSTR pszHeader = "Content-Type: text/html\r\n\r\n",
        LPCSTR pszStatusCode = "200 OK",                     
        BOOL fKeepConn=FALSE);                               
                                                             
    BOOL DoneWithSession(__in DWORD dwHttpStatusCode);       
    BOOL RequestIOCompletion(__in PFN_HSE_IO_COMPLETION pfn, 
        DWORD *pdwContext);                                  
                                                             
    BOOL TransmitFile(                                       
        HANDLE hFile,                                        
        PFN_HSE_IO_COMPLETION pfn,                           
        void *pContext,                                      
        LPCSTR szStatusCode,                                 
        DWORD dwBytesToWrite,                                
        DWORD dwOffset,                                      
        void *pvHead,                                        
        DWORD dwHeadLen,                                     
        void *pvTail,                                        
        DWORD dwTailLen,                                     
        DWORD dwFlags);                                      
                                                             
    BOOL AppendToLog(LPCSTR szMessage, DWORD *pdwLen);       
                                                             
    BOOL MapUrlToPathEx(LPCSTR szLogicalPath, DWORD dwLen,   
        HSE_URL_MAPEX_INFO *pumInfo);                        
};

The CServerContext class provides a somewhat more convenient wrapper for the ISAPI interface. Before you use it, you need to add an ATL module object to your project and initialize it in DLL main. This code takes care of the housekeeping:

// Our module class definition
class CHelloISAPI2Module :
  public CAtlDllModuleT<CHelloISAPI2Module> {};

// Required global instance of module.
CHelloISAPI2Module _AtlModule;

// Initialize / shutdown module on DLL load or unload
BOOL APIENTRY DllMain( HMODULE hModule,
  DWORD ul_reason_for_call, LPVOID lpReserved ) {
  // Set up shared data for use by CServerContext
  return _AtlModule.DllMain(ul_reason_for_call, lpReserved);
}

Having initialized shared data that CServerContext makes use of, we can now take advantage of CServerContext:

DWORD WINAPI HttpExtensionProc(EXTENSION_CONTROL_BLOCK *pECB) {
  CComObject< CServerContext > *pCtx;
  CComObject< CServerContext >::CreateInstance( &pCtx );
  pCtx->Initialize( pECB );
  // We use this smart pointer to ensure proper cleanup
  CComPtr< IUnknown > spContextUnk( pCtx );

  char *header =
    "<html>"
      "<head>"
        "<title>Hello from ISAPI</title> "
      "</head>"
      "<body>"
        "<h1>Hello from an ISAPI Extension</h1>";

  DWORD size = static_cast< DWORD >( strlen( header ) );
  pCtx->WriteClient( header, &size );

  char *intro = "<p>Your name is: ";
  size = static_cast< DWORD >( strlen( intro ) );
  pCtx->WriteClient( intro, &size );

  size = static_cast< DWORD >(
    strlen( pCtx->GetQueryString( ) ) );
  pCtx->WriteClient(
    const_cast< LPSTR >(pCtx->GetQueryString( )), &size );

  char *footer =
      "\r\n</body>\r\n"
  "</html>\r\n";

  size = static_cast< DWORD >( strlen( footer ) );
  pCtx->WriteClient( footer, &size );

  return HSE_STATUS_SUCCESS;
}

The bold lines show where we've replaced direct calls to the ECB with calls via the context. The WriteClient method is at least a little shorter, but we actually haven't gained much at this point. Luckily, there's more API wrapping to be done.

Request and Response Wrappers

Anyone who has done ASP or ASP.NET development is familiar with the Request and Response objects. The former gives access to the contents of the HTTP request: URL, query string, cookies, and so on. The latter gives you a way to write data to the output stream. ATL Server provides similar wrappers that make both reading and writing from the ECB much more pleasant.

The CHttpRequest object is a wrapper object that lets you get at the contents of the HTTP request:

class CHttpRequest : public IHttpRequestLookup {         
public:                                                  
  // Constructs and initializes the object.              
  CHttpRequest(                                          
    IHttpServerContext *pServerContext,                  
    DWORD dwMaxFormSize=DEFAULT_MAX_FORM_SIZE,           
    DWORD dwFlags=ATL_FORM_FLAG_NONE);                   
                                                         
  CHttpRequest(IHttpRequestLookup *pRequestLookup);      
                                                         
  // Access to Query String parameters as a collection   
  const CHttpRequestParams& GetQueryParams() const;      
                                                         
  // Get the entire raw query string                     
  LPCSTR GetQueryString();                               
                                                         
  ... Other methods omitted - we'll talk about them later
}; // class CHttpRequest

The CHttpRequest object gives you easy access to everything in the request. Using the CHttpRequest object simplifies getting at query string variables. In the raw C++ extension code, I cheated and just passed data (such as ?Chris), to make using that data easier. However, typical web pages take named query parameters separated with the ampersand (&) and potentially containing special characters encoded in hex:

http://localhost/HelloISAPI2/HelloISAP2.dll?name=Chris&motto=I%20Love%20ATL

Unfortunately, decoding and parsing query strings in their full glory requires quite a bit of work to get right, which is where ATL Server really starts to shine via the CHttpRequest class:

DWORD WINAPI HttpExtensionProc(EXTENSION_CONTROL_BLOCK *pECB) {
  CComObject< CServerContext > *pCtx;
  CComObject< CServerContext >::CreateInstance( &pCtx );
  pCtx->Initialize( pECB );
  // We use this smart pointer to ensure proper cleanup
  CComPtr< IUnknown > spContextUnk( pCtx );

  CHttpRequest request( pCtx );

  char *header =
    "<html>"
      "<head>"
        "<title>Hello from ISAPI</title>"
      "</head>"
      "<body>"
        "<h1>Hello from an ISAPI Extension</h1>";

  DWORD size = static_cast< DWORD >( strlen( header ) );
  pCtx->WriteClient( header, &size );

  CStringA name;
  name = request.GetQueryParams( ).Lookup( "name" );
  if( name.IsEmpty( ) ) {
    char *noName = "<p>You didn't give your name";
    size = static_cast< DWORD >( strlen( noName ) );
    pCtx->WriteClient( noName, &size );
  }
  else {
    char *intro = "<p>Your name is: ";
    size = static_cast< DWORD >( strlen( intro ) );
    pCtx->WriteClient( intro, &size );
    size = name.GetLength( );
    pCtx->WriteClient( name.GetBuffer( ), &size );
  }

  char *footer =
        "\r\n</p>\r\n"
      "\r\n</body>\r\n"
    "</html>\r\n";

  size = static_cast< DWORD >( strlen( footer ) );
  pCtx->WriteClient( footer, &size );

  return HSE_STATUS_SUCCESS;
}

The bold lines show where we're calling into the CHttpRequest object and parsing the named query parameter name. If it's encoded with embedded spaces or other special characters, or if it's included with other query parameters, ATL Server parses it correctly.

One minor thing that might seem odd is the use of CStringA in the previous code sample. Why didn't I just use the plain CString? If you look in the documentation for CHttpRequestParams::Lookup (the method I used to get the query string values), you'll see this:

class CHttpRequestParams : ... {     
  ...                                
  LPCSTR Lookup(LPCSTR szName) const;
  ...                                
};

Notice that the return type is LPCSTR, not LPCTSTR. In general, when dealing with strings coming in or going out via HTTP, ATL Server explicitly uses 8-bit ANSI character strings.

The CString class is actually a string of TCHARs. As you recall from Chapter 2, "Strings and Text," this means that the actual type of the underlying characters changes depending on your compile settings for Unicode. However, the return type for the Lookup method never changes: It's always ANSI. So, the sample code uses CStringA explicitly to say, "I don't care what the UNICODE compile setting is, I always want this to be 8-bit characters."

On the output side, ATL Server provides the CHttpResponse class:

class CHttpResponse :                                            
  public IWriteStream,                                           
  public CWriteStreamHelper {                                    
public:                                                          
  // Implementation: The buffer used to store the                
  // response before the data is sent to the client.             
  CAtlIsapiBuffer<> m_strContent;                                
                                                                 
  // Numeric constants for the HTTP status codes                 
  // used for redirecting client requests.                       
  enum HTTP_REDIRECT {                                           
    HTTP_REDIRECT_MULTIPLE=300,                                  
    HTTP_REDIRECT_MOVED=301,                                     
    HTTP_REDIRECT_FOUND=302,                                     
    HTTP_REDIRECT_SEE_OTHER=303,                                 
    HTTP_REDIRECT_NOT_MODIFIED=304,                              
    HTTP_REDIRECT_USE_PROXY=305,                                 
    HTTP_REDIRECT_TEMPORARY_REDIRECT=307                         
  };                                                             
                                                                 
  // Initialization                                              
                                                                 
  CHttpResponse();                                               
  CHttpResponse(IHttpServerContext *pServerContext);             
  BOOL Initialize(IHttpServerContext *pServerContext);           
  BOOL Initialize(IHttpRequestLookup *pLookup);                  
                                                                 
  // Writing to the output                                       
                                                                 
  BOOL SetContentType(LPCSTR szContentType);                     
  HRESULT WriteStream(LPCSTR szOut, int nLen, DWORD *pdwWritten);
  BOOL WriteLen(LPCSTR szOut, DWORD dwLen);                      
                                                                 
  // Redirect client to another URL                              
  BOOL Redirect(LPCSTR szUrl,                                    
    HTTP_REDIRECT statusCode=HTTP_REDIRECT_MOVED,                
    BOOL bSendBody=TRUE);                                        
  BOOL Redirect(LPCSTR szUrl, LPCSTR szBody,                     
    HTTP_REDIRECT statusCode=HTTP_REDIRECT_MOVED);               
                                                                 
  // Manipulate various response headers                         
                                                                 
  BOOL AppendHeader(LPCSTR szName, LPCSTR szValue);              
  BOOL AppendCookie(const CCookie *pCookie);                     
  BOOL AppendCookie(const CCookie& cookie);                      
  BOOL AppendCookie(LPCSTR szName, LPCSTR szValue);              
  BOOL DeleteCookie(LPCSTR szName);                              
                                                                 
  void ClearHeaders();                                           
  void ClearContent();                                           
                                                                 
  // Send the current buffer to the client                       
  BOOL Flush(BOOL bFinal=FALSE);                                 
  ... other methods omitted for clarity                          
  }                                                              
}; // class CHttpResponse

The CHttpResponse class provides all the control you need to manipulate the response going back to the client. But the best thing about CHttpResponse isn't in this class definitionit's in the base class, CWriteStreamHelper:

class CWriteStreamHelper {                             
public:                                                
  ... Other methods omitted for clarity                
                                                                 
  CWriteStreamHelper& operator<<(LPCSTR szStr);        
  CWriteStreamHelper& operator<<(LPCWSTR wszStr);      
  CWriteStreamHelper& operator<<(int n);               
  CWriteStreamHelper& operator<<(short int w);         
  CWriteStreamHelper& operator<<(unsigned int u);      
  CWriteStreamHelper& operator<<(long int dw);         
  CWriteStreamHelper& operator<<(unsigned long int dw);
  CWriteStreamHelper& operator<<(double d);            
  CWriteStreamHelper& operator<<(__int64 i);           
  CWriteStreamHelper& operator<<(unsigned t64 i);      
  CWriteStreamHelper& operator<<(CURRENCY c);          
};

These operator<< overloads mean that CHttpResponse can be used much like C++ iostreams can, and they make it much, much easier to build up your output. Using CHttpResponse, our final HttpExtensionProc now looks like this:

DWORD WINAPI HttpExtensionProc(EXTENSION_CONTROL_BLOCK *pECB) {
  CComObject< CServerContext > *pCtx;
  CComObject< CServerContext >::CreateInstance( &pCtx );
  pCtx->Initialize( pECB );
  // We use this smart pointer to ensure proper cleanup
  CComPtr< IUnknown > spContextUnk( pCtx );

  CHttpRequest request( pCtx );
  CHttpResponse response( pCtx );

  response << "<html>" <<
    "<head>" <<
      "<title>Hello from ISAPI</title>" <<
    "</head>" <<
    "<body>" <<
      "<h1>Hello from an ISAPI Extension</h1>";

  CStringA name;
  name = request.GetQueryParams( ).Lookup( "name" );
  if( name.IsEmpty( ) ) {
    response << "<p>You didn't give your name";
  } else {
    response << "<p>Your name is: " << name;
  }

  response << "</p>" <<
      "</body>" <<
    "</html>";

  return HSE_STATUS_SUCCESS;
}

This use of the CHttpResponse object gives us a much simpler programming model. All those ugly casts are gone, and we don't need to worry about presizing anything.

The use of the CServerContext, CHttpRequest, and CHttpResponse objects does make the basics of request processing easier, but other issues haven't yet been addressed. IIS does some subtle work with threading, and if you don't handle threads properly, you'll destroy your server's performance. There's also dealing with form fields and form validation, something every web app has to do. Finally, does it really make sense that you have to recompile your C++ code every time you want to change some HTML?

To address these issues, let's take a look at how ATL Server implements the ISAPI extension.