PFN_REGISTERMODULE Function

IIS 7.0
 

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

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

dwServerVersion

A DWORD that contains the IIS major version number.

pModuleInfo

A pointer to an IHttpModuleRegistrationInfo interface.

pGlobalInfo

A pointer to an IHttpServer interface.

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

Value

Description

S_OK

Indicates that the operation was successful.

System_CAPS_noteNote

Your module can return any valid HRESULT value, but it should return at least S_OK to indicate that your RegisterModule function was successful.

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.

System_CAPS_noteNote

Trace events should not be raised (through IHttpTraceContext::QuickTrace Method or any other means through IHttpServer::GetTraceContext Method) inside of the RegisterModule function implementation. Raising trace events inside of RegisterModule can cause an access violation as it is too early in the request pipeline.

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.

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 Technical Preview

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

Show: