PFN_REGISTERMODULE Function

Defines the RegisterModule function prototype for native-code HTTP modules.

Syntax

typedef HRESULT(WINAPI* PFN_REGISTERMODULE)(  
   DWORD dwServerVersion,  
   IHttpModuleRegistrationInfo* pModuleInfo,  
   IHttpServer* pGlobalInfo  
);  

Parameters

dwServerVersion
A DWORD that contains the IIS major version number.

pModuleInfo
A pointer to an IHttpModuleRegistrationInfo interface.

pGlobalInfo
A pointer to an IHttpServer interface.

Return Value

An HRESULT. Possible values include, but are not limited to, those in the following table.

Remarks

PFN_REGISTERMODULE is a function prototype for the RegisterModule function that all HTTP modules are required to implement for their DLL entry point.

When you create an HTTP module, your module needs to add the following RegisterModule method:

HRESULT RegisterModule(  
   DWORD dwServerVersion,  
   IHttpModuleRegistrationInfo* pModuleInfo,  
   IHttpServer* pGlobalInfo  
)  

All HTTP modules must export their RegisterModule function in order for IIS to load the module. You can export the RegisterModule function by creating a module definition (.def) file for your DLL project or compiling the module by using the /EXPORT:RegisterModule switch.

Your RegisterModule function will need to use the IHttpModuleRegistrationInfo interface to register for notifications by using the SetRequestNotifications and SetGlobalNotifications methods. RegisterModule will also need to use IHttpModuleRegistrationInfo to register module priorities by using the SetPriorityForRequestNotification and SetPriorityForGlobalNotification methods.

The dwServerVersion parameter contains the major version number for the version of IIS that loads the module. For example, for IIS 7.0 the dwServerVersion parameter will contain a 7.

When IIS calls your RegisterModule function, it provides an IHttpServer interface, which your module can use to retrieve server-level information.

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 CHttpModule::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

See Also

IHttpModuleRegistrationInfo Interface
IHttpModuleRegistrationInfo::SetGlobalNotifications Method
IHttpModuleRegistrationInfo::SetPriorityForGlobalNotification Method
IHttpModuleRegistrationInfo::SetPriorityForRequestNotification Method
IHttpModuleRegistrationInfo::SetRequestNotifications Method
IHttpServer Interface