Класс CHttpModule

Статья
07/19/2023

Определяет базовый класс для http-модулей уровня запроса.

Синтаксис

class CHttpModule

Методы

В следующей таблице перечислены методы, предоставляемые классом CHttpModule .

Имя	Описание
~CHttpModule	Отменяет выделение экземпляра `CHttpModule` класса .
CHttpModule	Инициализирует новый экземпляр класса `CHttpModule`.
Dispose	Освобождает все ресурсы, используемые текущим экземпляром класса `CHttpModule`.
OnAcquireRequestState	Представляет метод, который будет обрабатывать `AcquireRequestState` событие, которое происходит, когда IIS извлекает состояние для текущего запроса.
OnAsyncCompletion	Представляет метод, который будет обрабатывать событие асинхронного завершения, которое происходит после завершения обработки асинхронной операции.
OnAuthenticateRequest	Представляет метод, который будет обрабатывать `AuthenticateRequest` событие, которое возникает, когда СЛУЖБЫ IIS устанавливают удостоверение пользователя.
OnAuthorizeRequest	Представляет метод, который будет обрабатывать `AuthorizeRequest` событие, которое происходит, когда СЛУЖБЫ IIS проверяют авторизацию пользователя.
OnBeginRequest	Представляет метод, который будет обрабатывать `BeginRequest` событие, которое возникает как первое событие в конвейере обработки запросов, интегрированном с HTTP, для текущего запроса.
OnCustomRequestNotification	Представляет метод, который будет обрабатывать пользовательское событие, которое возникает, когда модуль создает определяемое пользователем уведомление.
OnEndRequest	Представляет метод, который будет обрабатывать `EndRequest` событие, которое возникает как последнее событие в конвейере обработки запросов, интегрированном с HTTP, для текущего запроса.
OnExecuteRequestHandler	Представляет метод, который будет обрабатывать `ExecuteRequestHandler` событие, которое происходит, когда IIS выполняет обработчик для текущего запроса.
OnLogRequest	Представляет метод, который будет обрабатывать `LogRequest` событие, которое происходит при подготовке IIS к регистрации текущего запроса.
OnMapPath	Представляет метод, который будет обрабатывать `MapPath` событие, которое происходит, когда операция запрашивает физический путь для сопоставления с текущим запросом.
OnMapRequestHandler	Представляет метод, который будет обрабатывать `MapRequestHandler` событие, которое происходит, когда IIS сопоставляет текущий запрос с обработчиком событий.
OnPostAcquireRequestState	Представляет метод, который будет обрабатывать `AcquireRequestState` событие после получения iis состояния текущего запроса.
OnPostAuthenticateRequest	Представляет метод, который будет обрабатывать событие, выполняемое `AuthenticateRequest` после установки iis удостоверения пользователя.
OnPostAuthorizeRequest	Представляет метод, который будет обрабатывать событие, выполняемое `AuthorizeRequest` после проверки авторизации пользователя iis.
OnPostBeginRequest	Представляет метод, который будет обрабатывать `BeginRequest` событие после выполнения, которое происходит после первого события в конвейере обработки запросов, интегрированного с HTTP.
OnPostEndRequest	Представляет метод, который будет обрабатывать событие, выполняемое `EndRequest` после последнего события в конвейере обработки запросов, интегрированного с HTTP, для текущего запроса.
OnPostExecuteRequestHandler	Представляет метод, который будет обрабатывать `ExecuteRequestHandler` событие после выполнения iis обработчика текущего запроса.
OnPostLogRequest	Представляет метод, который будет обрабатывать `LogRequest` событие после выполнения, которое происходит после того, как СЛУЖБЫ IIS зарегистрировали текущий запрос.
OnPostMapRequestHandler	Представляет метод, который будет обрабатывать событие, выполняемое `MapRequestHandler` после того, как IIS сопоставит текущий запрос с соответствующим обработчиком событий.
OnPostPreExecuteRequestHandler	Представляет метод, который будет обрабатывать событие, выполняемое `PreExecuteRequestHandler` после выполнения iis обработчика запросов.
OnPostReleaseRequestState	Представляет метод, который будет обрабатывать `ReleaseRequestState` событие после освобождения текущего состояния.
OnPostResolveRequestCache	Представляет метод, который будет обрабатывать `ResolveRequestCache` событие после выполнения, которое происходит после разрешения iis запроса из кэша.
OnPostUpdateRequestCache	Представляет метод, который будет обрабатывать событие, выполняемое `UpdateRequestCache` после того, как СЛУЖБЫ IIS сохранили запрос в кэше.
OnPreExecuteRequestHandler	Представляет метод, который будет обрабатывать `PreExecuteRequestHandler` событие, которое происходит до выполнения iis обработчика запросов.
OnReadEntity	Представляет метод, который будет обрабатывать `ReadEntity` событие, которое происходит, когда операция считывает данные из буфера запросов.
OnReleaseRequestState	Представляет метод, который будет обрабатывать `ReleaseRequestState` событие, которое возникает при освобождении текущего состояния.
OnResolveRequestCache	Представляет метод, который будет обрабатывать `ResolveRequestCache` событие, которое возникает при разрешении iis запроса в кэше.
OnSendResponse	Представляет метод, который будет обрабатывать `SendResponse` событие, которое происходит при отправке iis буфера ответов.
OnUpdateRequestCache	Представляет метод, который будет обрабатывать `UpdateRequestCache` событие, которое происходит, когда IIS сохраняет запрос в кэше.

Производные классы

Этот класс не содержит производных классов.

Класс CHttpModule является базовым классом для http-модулей уровня запроса. Чтобы создать производный CHttpModuleот класса, необходимо создать HTTP-модуль уровня запроса, содержащий класс, наследующий от , и класс, производный от CHttpModule интерфейса IHttpModuleFactory . Дополнительные сведения о создании модулей HTTP см. в разделе Проектирование Native-Code HTTP-модулей.

Класс CHttpModule предоставляет защищенные методы конструктора и деструктора, а также открытый Dispose метод. В конце запроса вызывается метод для Dispose удаления экземпляра производного от CHttpModuleкласса .

Класс CHttpModule также определяет методы уведомлений, которые IIS 7 вызывает при обработке событий уровня запроса в интегрированном конвейере обработки запросов. Модуль HTTP может регистрироваться для определенных событий, определяя список уведомлений в экспортируемой функции RegisterModule модуля.

События детерминированного запроса

Большинство методов уведомления на уровне запроса обрабатываются в хронологическом порядке во время обычного потока событий уровня запроса в интегрированном конвейере. Каждый из детерминированных методов уведомления на уровне запроса имеет соответствующее уведомление после события, что позволяет модулям HTTP обрабатывать при возникновении события или сразу после него.

В следующей таблице перечислены хронологические методы уведомления на уровне запроса и уведомления после события в порядке их возникновения в интегрированном конвейере.

Метод уведомления о событиях	Метод уведомления о событиях после события
`OnBeginRequest`	`OnPostBeginRequest`
`OnAuthenticateRequest`	`OnPostAuthenticateRequest`
`OnAuthorizeRequest`	`OnPostAuthorizeRequest`
`OnResolveRequestCache`	`OnPostResolveRequestCache`
`OnMapRequestHandler`	`OnPostMapRequestHandler`
`OnAcquireRequestState`	`OnPostAcquireRequestState`
`OnPreExecuteRequestHandler`	`OnPostPreExecuteRequestHandler`
`OnExecuteRequestHandler`	`OnPostExecuteRequestHandler`
`OnReleaseRequestState`	`OnPostReleaseRequestState`
`OnUpdateRequestCache`	`OnPostUpdateRequestCache`
`OnLogRequest`	`OnPostLogRequest`
`OnEndRequest`	`OnPostEndRequest`

Например, OnBeginRequest происходит до OnAuthenticateRequest, OnMapRequestHandler происходит до OnAcquireRequestStateи т. д.

Примечание

Уведомления о последующих событиях происходят до следующего уведомления на уровне запроса в хронологическом порядке. Например, OnPostAuthenticateRequest происходит до OnAuthorizeRequest, OnPostUpdateRequestCache происходит до OnLogRequestи т. д.

События недетерминированного запроса

Остальные методы уведомления на уровне запроса не обрабатываются в определенном порядке; вместо этого IIS обрабатывает эти события при возникновении определенного недетерминированного события. В следующей таблице перечислены недетерминированные события уровня запроса и все связанные методы уведомления после события.

Метод уведомления о событиях	Метод уведомления о событиях после события
`OnAsyncCompletion`	(Нет) ¹
`OnCustomRequestNotification`	(Нет) ²
`OnMapPath`	(нет)
`OnReadEntity`	(нет)
`OnSendResponse`	(нет)

¹ Метод OnAsyncCompletion вызывается при возникновении асинхронного события в модуле HTTP. Таким образом, вы не можете зарегистрировать асинхронное уведомление с помощью экспортируемой функции RegisterModule модуля. Вместо этого модуль будет предоставлять OnAsyncCompletion метод для обработки уведомлений, которые возникают после вызова методов, возвращающих асинхронно (например, методы IHttpContext::ExecuteRequest и IHttpResponse::WriteEntityChunks ). При вызове OnAsyncCompletionслужб IIS метод передает параметры, которые указывают тип уведомления и указывает, было ли уведомление для события или после события.

² Метод OnCustomRequestNotification не имеет соответствующего метода уведомления после события. Модуль HTTP может зарегистрировать пользовательское уведомление с помощью экспортируемой RegisterModule функции модуля, но модуль не может зарегистрировать уведомление, которое происходит после создания пользовательского уведомления.

Пример

В следующем примере показано, как создать простой модуль HTTP "Hello World". Модуль определяет экспортированную RegisterModule функцию, которая передает экземпляр IHttpModuleFactory интерфейса методу IHttpModuleRegistrationInfo::SetRequestNotifications и регистрирует для уведомления RQ_BEGIN_REQUEST . IIS использует метод IHttpModuleFactory::GetHttpModule для создания экземпляра класса и возвращает состояние успешного CHttpModule выполнения. IIS также использует метод IHttpModuleFactory::Terminate для удаления фабрики из памяти.

При появлении RQ_BEGIN_REQUEST уведомления СЛУЖБЫ IIS вызывает метод модуля OnBeginRequest для обработки текущего запроса. OnBeginRequest очищает буфер ответа и изменяет тип MIME для ответа. Затем метод создает блок данных, содержащий строку "Hello World", и возвращает строку веб-клиенту. Наконец, модуль возвращает индикатор состояния, который уведомляет IIS о завершении всех уведомлений, а затем завершает работу.

#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
    );
}

Модуль должен экспортировать функцию RegisterModule . Эту функцию можно экспортировать, создав файл определения модуля (DEF- файл) для проекта, или скомпилировать модуль с помощью /EXPORT:RegisterModule параметра . Дополнительные сведения см. в разделе Пошаговое руководство. Создание модуля HTTP Request-Level с помощью машинного кода.

При необходимости можно скомпилировать код с помощью __stdcall (/Gz) соглашения о вызовах вместо явного объявления соглашения о вызовах для каждой функции.

Требования

Тип	Описание
клиент	— IIS 7.0 в Windows Vista — IIS 7.5 в Windows 7 — IIS 8.0 в Windows 8 — IIS 10.0 в Windows 10
Сервер	— IIS 7.0 в Windows Server 2008 — IIS 7.5 в Windows Server 2008 R2 — IIS 8.0 в Windows Server 2012 — IIS 8.5 в Windows Server 2012 R2 — IIS 10.0 в Windows Server 2016
Продукт	— 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
Заголовок	Httpserv.h

См. также:

Создание Native-Code модулей HTTP
Класс CGlobalModule

Поделиться через