IHttpContext::GetNextNotification Method

Article
05/24/2022

Retrieves the next notification for the current module host.

Syntax

virtual BOOL GetNextNotification(  
   IN REQUEST_NOTIFICATION_STATUS status,  
   OUT DWORD* pdwNotification,  
   OUT BOOL* pfIsPostNotification,  
   OUT CHttpModule** ppModuleInfo,  
   OUT IHttpEventProvider** ppRequestOutput  
) = 0;

Parameters

status
[IN] The REQUEST_NOTIFICATION_STATUS enumeration value to return from the current notification.

pdwNotification
[OUT] A pointer to a DWORD that contains the bitmask value for the next notification.

pfIsPostNotification
[OUT] A pointer to a Boolean value. true to indicate that the notification is a post-notification; otherwise, false.

ppModuleInfo
[OUT] A pointer to the address of the CHttpModule class that is responsible for processing the returned notification.

ppRequestOutput
[OUT] A pointer to the address of the IHttpEventProvider interface for the returned notification.

Return Value

true if the call to GetNextNotification was successful; otherwise, false.

Remarks

HTTP modules can use the GetNextNotification method to merge notifications within the same module host. Returning processing to the integrated request-processing pipeline requires a small amount of overhead. To bypass that overhead, an HTTP module can call the GetNextNotification method to skip to the next notification and continue processing, provided that the two notifications are within the same module host and no additional notification handlers are registered to process a request between notifications.

For example, an HTTP module might contain an OnResolveRequestCache method, and another HTTP module within the same module host might contain an OnPostResolveRequestCache method. The first module can call the GetNextNotification method to continue processing, rather than returning processing to the pipeline, as though the module had already registered for the OnPostResolveRequestCache post-event notification method.

Note

If the call to GetNextNotification returns false, you can enable a failed-request-tracing rule that will allow you to examine which notifications IIS is processing.

Example

The following code example demonstrates how to create an HTTP module that performs the following tasks:

Registers for several notifications.
Creates a helper method that calls the GetNextNotification method, which attempts to skip to the next notification.
For each registered notification, defines notification handlers that call the helper method, and then displays the return status to the client.

#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <httpserv.h>

// Create the module class.
class MyHttpModule : public CHttpModule
{
public:
    REQUEST_NOTIFICATION_STATUS
    OnBeginRequest(
        IN IHttpContext * pHttpContext,
        IN IHttpEventProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );

        // Clear the existing response.
        pHttpContext->GetResponse()->Clear();
        // Set the MIME type to plain text.
        pHttpContext->GetResponse()->SetHeader(
            HttpHeaderContentType,"text/plain",
            (USHORT)strlen("text/plain"),TRUE);

        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }

    REQUEST_NOTIFICATION_STATUS
    OnAuthenticateRequest(
        IN IHttpContext * pHttpContext,
        IN IAuthenticationProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );
        // Attempt to retrieve the next notification and display the result.
        GetNotificationAndDisplayResult(
            pHttpContext,"OnAuthenticateRequest\n");
        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }

    REQUEST_NOTIFICATION_STATUS
    OnPostAuthenticateRequest(
        IN IHttpContext * pHttpContext,
        IN IHttpEventProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );
        // Attempt to retrieve the next notification and display the result.
        GetNotificationAndDisplayResult(
            pHttpContext,"\nOnPostAuthenticateRequest\n");
        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }

    REQUEST_NOTIFICATION_STATUS
    OnAuthorizeRequest(
        IN IHttpContext * pHttpContext,
        IN IHttpEventProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );
        // Attempt to retrieve the next notification and display the result.
        GetNotificationAndDisplayResult(
            pHttpContext,"\nOnAuthorizeRequest\n");
        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }

    REQUEST_NOTIFICATION_STATUS
    OnPostAuthorizeRequest(
        IN IHttpContext * pHttpContext,
        IN IHttpEventProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pProvider );
        // Attempt to retrieve the next notification and display the result.
        GetNotificationAndDisplayResult(
            pHttpContext,"\nOnPostAuthorizeRequest\n");
        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }

    REQUEST_NOTIFICATION_STATUS
    OnMapRequestHandler(
        IN IHttpContext * pHttpContext,
        IN IMapHandlerProvider * pProvider
    )
    {
        UNREFERENCED_PARAMETER( pHttpContext );
        UNREFERENCED_PARAMETER( pProvider );
        // End additional processing.        
        return RQ_NOTIFICATION_FINISH_REQUEST;
    }

private:

    // Create a helper method that attempts to retrieve the next
    // notification and returns the status to a Web client.
    void GetNotificationAndDisplayResult(
        IHttpContext * pHttpContext,
        PCSTR pszBuffer
    )
    {
        DWORD dwNotification = 0;
        BOOL fPostNotification = FALSE;
        CHttpModule * pHttpModule = NULL;
        IHttpEventProvider * pEventProvider = NULL;
        char szBuffer[256]="";

        // Attempt to retrive the next notification.
        BOOL fReturn = pHttpContext->GetNextNotification(
            RQ_NOTIFICATION_CONTINUE,
            &dwNotification,&fPostNotification,
            &pHttpModule,&pEventProvider);

        // Return the name of the notification to a Web client.
        WriteResponseMessage(pHttpContext,pszBuffer);

        // Return the status of the GetNextNotification method to a Web client.
        sprintf_s(szBuffer,255,"\tGetNextNotification return value: %s\n",
            fReturn==TRUE?"true":"false");
        WriteResponseMessage(pHttpContext,szBuffer);

        // Return the notification bitmask to a Web client.
        sprintf_s(szBuffer,255,"\tNotification: %08x\n",dwNotification);
        WriteResponseMessage(pHttpContext,szBuffer);

        // Return whether the notification is a post-notification.
        sprintf_s(szBuffer,255,"\tPost-notification: %s\n",
            fPostNotification==TRUE?"Yes":"No");
        WriteResponseMessage(pHttpContext,szBuffer);
    }

    // Create a utility method that inserts a string value into the response.
    HRESULT WriteResponseMessage(
        IHttpContext * pHttpContext,
        PCSTR pszBuffer
    )
    {
        // Create an HRESULT to receive return values from methods.
        HRESULT hr;
        
        // Create a data chunk. (Defined in the Http.h file.)
        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 = pHttpContext->GetResponse()->WriteEntityChunks(
            &dataChunk,1,FALSE,TRUE,&cbSent);
        // Test for an error.
        if (FAILED(hr))
        {
            // Return the error status.
            return hr;
        }

        // Return a success status.
        return S_OK;
    }
};

// Create the module's class factory.
class MyHttpModuleFactory : public IHttpModuleFactory
{
public:
    HRESULT
    GetHttpModule(
        OUT CHttpModule ** ppModule, 
        IN IModuleAllocator * pAllocator
    )
    {
        UNREFERENCED_PARAMETER( pAllocator );

        // Create a new instance.
        MyHttpModule * pModule = new MyHttpModule;

        // Test for an error.
        if (!pModule)
        {
            // Return an error if we 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 );

    return pModuleInfo->SetRequestNotifications(
        new MyHttpModuleFactory,
        RQ_BEGIN_REQUEST | RQ_AUTHENTICATE_REQUEST | 
        RQ_AUTHORIZE_REQUEST | RQ_MAP_REQUEST_HANDLER,
        RQ_AUTHENTICATE_REQUEST | RQ_AUTHORIZE_REQUEST
    );
}

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