Export (0) Print
Expand All
Expand Minimize

CHttpModule Class

IIS 7.0

Defines the base class for request-level HTTP modules.

class CHttpModule

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.

This class contains no derived classes.

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.

NoteNote:

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.

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.

Type

Description

Client

  • IIS 7.0 on Windows Vista

  • IIS 7.5 on Windows 7

  • IIS Express 7.5 on Windows XP, Windows Vista, Windows 7

  • IIS 8.0 on Windows 8 Client

Server

  • IIS 7.0 on Windows Server 2008

  • IIS 7.5 on Windows Server 2008 R2

  • IIS Express 7.5 on Windows Server 2003, Windows Server 2008, Windows Server 2008 R2

  • IIS 8.0 on Windows 8 Server

Product

IIS 7.0, IIS 7.5, IIS Express 7.5, IIS 8.0

Header

Httpserv.h

Community Additions

ADD
Show:
© 2014 Microsoft