CHttpModule Class

Article
05/19/2022

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)¹
`OnCustomRequestNotification`	(None)²
`OnMapPath`	(None)
`OnReadEntity`	(None)
`OnSendResponse`	(None)

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

Share via