IIS 7.0: CHttpModule Class

This page is specific to

Microsoft Visual Studio 2005/.NET Framework 2.0

Other versions are also available for the following:

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Defines the base class for request-level HTTP modules.

class CHttpModule

Methods

The following table lists the methods exposed by the CHttpModule class.

Name	Description
~CHttpModule	Deallocates an instance of the CHttpModule class.
CHttpModule	Initializes a new instance of the CHttpModule class.
Dispose	Releases all resources used by the current instance of the CHttpModule class.
OnAcquireRequestState	Represents the method that will handle an AcquireRequestState event, which occurs when IIS retrieves the state for the current request.
OnAsyncCompletion	Represents the method that will handle an asynchronous completion event, which occurs after an asynchronous operation has finished processing.
OnAuthenticateRequest	Represents the method that will handle an AuthenticateRequest event, which occurs when IIS establishes the identity of a user.
OnAuthorizeRequest	Represents the method that will handle an AuthorizeRequest event, which occurs when IIS verifies user authorization.
OnBeginRequest	Represents the method that will handle a BeginRequest event, which occurs as the first event in the HTTP integrated request-processing pipeline for the current request.
OnCustomRequestNotification	Represents the method that will handle a custom event, which occurs when a module raises a user-defined notification.
OnEndRequest	Represents the method that will handle an EndRequest event, which occurs as the last event in the HTTP integrated request-processing pipeline for the current request.
OnExecuteRequestHandler	Represents the method that will handle an ExecuteRequestHandler event, which occurs when IIS executes the handler for the current request.
OnLogRequest	Represents the method that will handle a LogRequest event, which occurs when IIS prepares to log the current request.
OnMapPath	Represents the method that will handle a MapPath event, which occurs when an operation requests the physical path to be mapped for the current request.
OnMapRequestHandler	Represents the method that will handle a MapRequestHandler event, which occurs when IIS maps the current request to an event handler.
OnPostAcquireRequestState	Represents the method that will handle an AcquireRequestState post-event, which occurs after IIS has retrieved the state for the current request.
OnPostAuthenticateRequest	Represents the method that will handle an AuthenticateRequest post-event, which occurs after IIS has established the identity of a user.
OnPostAuthorizeRequest	Represents the method that will handle an AuthorizeRequest post-event, which occurs after IIS has verified user authorization.
OnPostBeginRequest	Represents the method that will handle a BeginRequest post-event, which occurs after the first event in the HTTP integrated request-processing pipeline.
OnPostEndRequest	Represents the method that will handle an EndRequest post-event, which occurs after the last event in the HTTP integrated request-processing pipeline for the current request.
OnPostExecuteRequestHandler	Represents the method that will handle an ExecuteRequestHandler post-event, which occurs after IIS executes the handler for the current request.
OnPostLogRequest	Represents the method that will handle a LogRequest post-event, which occurs after IIS has logged the current request.
OnPostMapPath	Represents the method that will handle a MapPath post-event, which occurs after IIS has mapped the physical path for the current request.
OnPostMapRequestHandler	Represents the method that will handle a MapRequestHandler post-event, which occurs after IIS has mapped the current request to the appropriate event handler.
OnPostPreExecuteRequestHandler	Represents the method that will handle a PreExecuteRequestHandler post-event, which occurs before IIS executes a request handler.
OnPostReadEntity	Represents the method that will handle a ReadEntity post-event, which occurs after an operation has read data from the request buffer.
OnPostReleaseRequestState	Represents the method that will handle a ReleaseRequestState post-event, which occurs after the current state has been released.
OnPostResolveRequestCache	Represents the method that will handle a ResolveRequestCache post-event, which occurs after IIS has resolved a request from the cache.
OnPostSendResponse	Represents the method that will handle a SendResponse post-event, which occurs after IIS has sent the response buffer.
OnPostUpdateRequestCache	Represents the method that will handle an UpdateRequestCache post-event, which occurs after IIS has stored the request in the cache.
OnPreExecuteRequestHandler	Represents the method that will handle a PreExecuteRequestHandler event, which occurs before IIS executes a request handler.
OnReadEntity	Represents the method that will handle a ReadEntity event, which occurs when an operation reads data from the request buffer.
OnReleaseRequestState	Represents the method that will handle a ReleaseRequestState event, which occurs when the current state is released.
OnResolveRequestCache	Represents the method that will handle a ResolveRequestCache event, which occurs when IIS resolves a request in the cache.
OnSendResponse	Represents the method that will handle a SendResponse event, which occurs when IIS sends the response buffer.
OnUpdateRequestCache	Represents the method that will handle an UpdateRequestCache event, which occurs when IIS stores the request in the cache.

Subclasses

This class contains no subclasses.

Remarks

The CHttpModule class is the base class for request-level HTTP modules. Request-level HTTP modules must contain a class that inherits from CHttpModule, and a module will create the instance of the inherited class by using an IHttpModuleFactory. For more information about creating HTTP modules, see IIS 7.0: Designing Native-Code HTTP Modules.

The CHttpModule class provides protected constructor and destructor methods and a public Dispose method that is used to remove the class instance.

The CHttpModule class also defines the notification-specific methods that IIS 7.0 calls when it processes request-level events within the integrated request-processing pipeline. An HTTP module can register for specific events by defining a list of notifications in a module's exported RegisterModule function.

Deterministic request events

The majority of the request-level notification methods are processed chronologically during the normal flow of request-level events within the integrated pipeline. Each of the deterministic request-level notification methods has a matching post-event notification, which allows HTTP modules to process when an event occurs or immediately after the event occurs.

The following table lists the chronological request-level event and post-event notification methods in the order of their occurrence within the integrated pipeline.

Event notification method	Post-event notification method
OnBeginRequest	OnPostBeginRequest
OnAuthenticateRequest	OnPostAuthenticateRequest
OnAuthorizeRequest	OnPostAuthorizeRequest
OnResolveRequestCache	OnPostResolveRequestCache
OnMapRequestHandler	OnPostMapRequestHandler
OnAcquireRequestState	OnPostAcquireRequestState
OnPreExecuteRequestHandler	OnPostPreExecuteRequestHandler
OnExecuteRequestHandler	OnPostExecuteRequestHandler
OnReleaseRequestState	OnPostReleaseRequestState
OnUpdateRequestCache	OnPostUpdateRequestCache
OnLogRequest	OnPostLogRequest
OnEndRequest	OnPostEndRequest

For example, OnBeginRequest occurs before OnAuthenticateRequest, OnMapRequestHandler occurs before OnAcquireRequestState, and so on.

Note
Post-event notifications occur before the next chronological request-level notification. For example, OnPostAuthenticateRequest occurs before OnAuthorizeRequest, OnPostUpdateRequestCache occurs before OnLogRequest, and so on.

Nondeterministic request events

The remaining request-level notification methods are not processed in any specific order; instead, IIS processes these events when a specific nondeterministic event occurs. The following table lists the nondeterministic request-level event and any related post-event notification methods.

Event notification method	Post-event notification method
OnAsyncCompletion	(None)¹
OnCustomRequestNotification	(None)²
OnMapPath	OnPostMapPath
OnReadEntity	OnPostReadEntity
OnSendResponse	OnPostSendResponse

¹ The OnAsyncCompletion method is called when an asynchronous event occurs within an HTTP module. As such, you cannot register for an asynchronous notification by using a module's exported RegisterModule function. Instead, your module would supply an OnAsyncCompletion method to process notifications that occur after calling methods that return asynchronously (for example, the IHttpContext::ExecuteRequest and IHttpResponse::WriteEntityChunks methods). When IIS calls OnAsyncCompletion, the method will pass parameters that indicate the notification type and whether the notification was for an event or post-event.

² The OnCustomRequestNotification method does not have a corresponding post-event notification method. An HTTP module can register for a custom notification by using the module's exported RegisterModule function, but a module cannot register for a notification that occurs after a custom notification has occurred.

Example

The following code example demonstrates how to create a simple "Hello World" HTTP module. The module defines an exported RegisterModule function that passes an instance of an IHttpModuleFactory interface to the IHttpModuleRegistrationInfo::SetRequestNotifications method and registers for the RQ_BEGIN_REQUEST notification. IIS uses the IHttpModuleFactory::GetHttpModule method to create an instance of a CHttpModule class and returns a success status. IIS also uses the IHttpModuleFactory::Terminate method to remove the factory from memory.

When an RQ_BEGIN_REQUEST notification occurs, IIS calls the module's OnBeginRequest method to process the current request. OnBeginRequest clears the response buffer and modifies the MIME type for the response. The method then creates a data chunk that contains a "Hello World" string and returns the string to a Web client. Finally, the module returns a status indicator that notifies IIS that all notifications are finished and then exits.

#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <httpserv.h>

// Create the module class.
class CHelloWorld : public CHttpModule
{
public:
    REQUEST_NOTIFICATION_STATUS
    OnBeginRequest(
        IN IHttpContext * pHttpContext,
        IN IHttpEventProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );

        // Create an HRESULT to receive return values from methods.
        HRESULT hr;
        
        // Retrieve a pointer to the response.
        IHttpResponse * pHttpResponse = pHttpContext->GetResponse();

        // Test for an error.
        if (pHttpResponse != NULL)
        {
            // Clear the existing response.
            pHttpResponse->Clear();
            // Set the MIME type to plain text.
            pHttpResponse->SetHeader(
                HttpHeaderContentType,"text/plain",
                (USHORT)strlen("text/plain"),TRUE);

            // Create a string with the response.
            PCSTR pszBuffer = "Hello World!";
            // Create a data chunk.
            HTTP_DATA_CHUNK dataChunk;
            // Set the chunk to a chunk in memory.
            dataChunk.DataChunkType = HttpDataChunkFromMemory;
            // Buffer for bytes written of data chunk.
            DWORD cbSent;
            
            // Set the chunk to the buffer.
            dataChunk.FromMemory.pBuffer =
                (PVOID) pszBuffer;
            // Set the chunk size to the buffer size.
            dataChunk.FromMemory.BufferLength =
                (USHORT) strlen(pszBuffer);
            // Insert the data chunk into the response.
            hr = pHttpResponse->WriteEntityChunks(
                &dataChunk,1,FALSE,TRUE,&cbSent);

            // Test for an error.
            if (FAILED(hr))
            {
                // Set the HTTP status.
                pHttpResponse->SetStatus(500,"Server Error",0,hr);
            }

            // End additional processing.
            return RQ_NOTIFICATION_FINISH_REQUEST;
        }

        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }
};

// Create the module's class factory.
class CHelloWorldFactory : public IHttpModuleFactory
{
public:
    HRESULT
    GetHttpModule(
        OUT CHttpModule ** ppModule, 
        IN IModuleAllocator * pAllocator
    )
    {
        UNREFERENCED_PARAMETER( pAllocator );

        // Create a new instance.
        CHelloWorld * pModule = new CHelloWorld;

        // Test for an error.
        if (!pModule)
        {
            // Return an error if the factory cannot create the instance.
            return HRESULT_FROM_WIN32( ERROR_NOT_ENOUGH_MEMORY );
        }
        else
        {
            // Return a pointer to the module.
            *ppModule = pModule;
            pModule = NULL;
            // Return a success status.
            return S_OK;
        }            
    }

    void
    Terminate()
    {
        // Remove the class from memory.
        delete this;
    }
};

// Create the module's exported registration function.
HRESULT
__stdcall
RegisterModule(
    DWORD dwServerVersion,
    IHttpModuleRegistrationInfo * pModuleInfo,
    IHttpServer * pGlobalInfo
)
{
    UNREFERENCED_PARAMETER( dwServerVersion );
    UNREFERENCED_PARAMETER( pGlobalInfo );

    // Set the request notifications and exit.
    return pModuleInfo->SetRequestNotifications(
        new CHelloWorldFactory,
        RQ_BEGIN_REQUEST,
        0
    );
}

Your module must export the RegisterModule function. You can export this function by creating a module definition (.def) file for your project, or you can compile the module by using the /EXPORT:RegisterModule switch. For more information, see IIS 7.0: Walkthrough: Creating a Request-Level HTTP Module By Using Native Code.

You can optionally compile the code by using the __stdcall (/Gz) calling convention instead of explicitly declaring the calling convention for each function.

Requirements

Type	Description
Client	Requires IIS 7.0 on Windows Vista.
Server	Requires IIS 7.0 on Windows Vista.
Product	IIS 7.0
Header	Httpserv.h

Reference

IIS 7.0: CGlobalModule Class

Other Resources

IIS 7.0: Creating Native-Code HTTP Modules

Product Families

Resources

About Microsoft

Popular Places

Popular Searches

Popular Downloads

Deterministic request events

Nondeterministic request events

Reference

Other Resources