CHttpModule Class

Defines the base class for request-level HTTP modules.

Syntax

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.
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.
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.
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.

Derived Classes

This class contains no derived classes.

Remarks

The CHttpModule class is the base class for request-level HTTP modules. To create a CHttpModule-derived class, you need to create a request-level HTTP module that contains a class that inherits from CHttpModule and a class that derives from the IHttpModuleFactory interface. For more information about creating HTTP modules, see Designing Native-Code HTTP Modules.

The CHttpModule class provides protected constructor and destructor methods and a public Dispose method. At the end of the request, the Dispose method is called to delete the instance of the CHttpModule-derived class.

The CHttpModule class also defines the notification-specific methods that IIS 7 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)1
OnCustomRequestNotification (None)2
OnMapPath (None)
OnReadEntity (None)
OnSendResponse (None)

1 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.

2 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 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 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 - IIS 7.0 on Windows Vista
- IIS 7.5 on Windows 7
- IIS 8.0 on Windows 8
- IIS 10.0 on Windows 10
Server - IIS 7.0 on Windows Server 2008
- IIS 7.5 on Windows Server 2008 R2
- IIS 8.0 on Windows Server 2012
- IIS 8.5 on Windows Server 2012 R2
- IIS 10.0 on Windows Server 2016
Product - IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0
- IIS Express 7.5, IIS Express 8.0, IIS Express 10.0
Header Httpserv.h

See Also

Creating Native-Code HTTP Modules
CGlobalModule Class