Classe CHttpModule

Artigo
07/19/2023

Define a classe base para módulos HTTP no nível da solicitação.

Syntax

class CHttpModule

Métodos

A tabela a seguir lista os métodos expostos pela CHttpModule classe .

Nome	Descrição
~CHttpModule	Desaloca uma instância da `CHttpModule` classe .
CHttpModule	Inicializa uma nova instância da classe `CHttpModule`.
Dispose	Libera todos os recursos usados pela instância atual da classe `CHttpModule`.
OnAcquireRequestState	Representa o método que manipulará um `AcquireRequestState` evento, que ocorre quando o IIS recupera o estado da solicitação atual.
OnAsyncCompletion	Representa o método que manipulará um evento de conclusão assíncrona, que ocorre após a conclusão do processamento de uma operação assíncrona.
OnAuthenticateRequest	Representa o método que manipulará um `AuthenticateRequest` evento, que ocorre quando o IIS estabelece a identidade de um usuário.
OnAuthorizeRequest	Representa o método que manipulará um `AuthorizeRequest` evento, que ocorre quando o IIS verifica a autorização do usuário.
OnBeginRequest	Representa o método que manipulará um `BeginRequest` evento, que ocorre como o primeiro evento no pipeline de processamento de solicitações integrado a HTTP para a solicitação atual.
OnCustomRequestNotification	Representa o método que manipulará um evento personalizado, que ocorre quando um módulo gera uma notificação definida pelo usuário.
OnEndRequest	Representa o método que manipulará um `EndRequest` evento, que ocorre como o último evento no pipeline de processamento de solicitações integrado a HTTP para a solicitação atual.
OnExecuteRequestHandler	Representa o método que manipulará um `ExecuteRequestHandler` evento, que ocorre quando o IIS executa o manipulador para a solicitação atual.
OnLogRequest	Representa o método que manipulará um `LogRequest` evento, que ocorre quando o IIS se prepara para registrar a solicitação atual.
OnMapPath	Representa o método que manipulará um `MapPath` evento, que ocorre quando uma operação solicita que o caminho físico seja mapeado para a solicitação atual.
OnMapRequestHandler	Representa o método que manipulará um `MapRequestHandler` evento, que ocorre quando o IIS mapeia a solicitação atual para um manipulador de eventos.
OnPostAcquireRequestState	Representa o método que manipulará um `AcquireRequestState` pós-evento, que ocorre depois que o IIS recuperar o estado da solicitação atual.
OnPostAuthenticateRequest	Representa o método que manipulará um `AuthenticateRequest` pós-evento, que ocorre depois que o IIS estabeleceu a identidade de um usuário.
OnPostAuthorizeRequest	Representa o método que manipulará um `AuthorizeRequest` pós-evento, que ocorre após o IIS ter verificado a autorização do usuário.
OnPostBeginRequest	Representa o método que manipulará um `BeginRequest` pós-evento, que ocorre após o primeiro evento no pipeline de processamento de solicitação integrado a HTTP.
OnPostEndRequest	Representa o método que manipulará um `EndRequest` pós-evento, que ocorre após o último evento no pipeline de processamento de solicitação integrado a HTTP para a solicitação atual.
OnPostExecuteRequestHandler	Representa o método que manipulará um `ExecuteRequestHandler` pós-evento, que ocorre após o IIS executar o manipulador para a solicitação atual.
OnPostLogRequest	Representa o método que manipulará um `LogRequest` pós-evento, que ocorre após o IIS ter registrado a solicitação atual.
OnPostMapRequestHandler	Representa o método que manipulará um `MapRequestHandler` pós-evento, que ocorre depois que o IIS mapeou a solicitação atual para o manipulador de eventos apropriado.
OnPostPreExecuteRequestHandler	Representa o método que manipulará um `PreExecuteRequestHandler` pós-evento, que ocorre antes do IIS executar um manipulador de solicitação.
OnPostReleaseRequestState	Representa o método que manipulará um `ReleaseRequestState` pós-evento, que ocorre após o lançamento do estado atual.
OnPostResolveRequestCache	Representa o método que manipulará um `ResolveRequestCache` pós-evento, que ocorre depois que o IIS resolveu uma solicitação do cache.
OnPostUpdateRequestCache	Representa o método que manipulará um `UpdateRequestCache` pós-evento, que ocorre depois que o IIS armazenar a solicitação no cache.
OnPreExecuteRequestHandler	Representa o método que manipulará um `PreExecuteRequestHandler` evento, que ocorre antes que o IIS execute um manipulador de solicitação.
OnReadEntity	Representa o método que manipulará um `ReadEntity` evento, que ocorre quando uma operação lê dados do buffer de solicitação.
OnReleaseRequestState	Representa o método que manipulará um `ReleaseRequestState` evento, que ocorre quando o estado atual é liberado.
OnResolveRequestCache	Representa o método que manipulará um `ResolveRequestCache` evento, que ocorre quando o IIS resolve uma solicitação no cache.
OnSendResponse	Representa o método que manipulará um `SendResponse` evento, que ocorre quando o IIS envia o buffer de resposta.
OnUpdateRequestCache	Representa o método que manipulará um `UpdateRequestCache` evento, que ocorre quando o IIS armazena a solicitação no cache.

Classes derivadas

Essa classe não contém classes derivadas.

Comentários

A CHttpModule classe é a classe base para módulos HTTP no nível da solicitação. Para criar uma CHttpModuleclasse derivada de , você precisa criar um módulo HTTP no nível da solicitação que contenha uma classe que herda de CHttpModule e uma classe que deriva da interface IHttpModuleFactory . Para obter mais informações sobre como criar módulos HTTP, consulte Criando módulos HTTP Native-Code.

A CHttpModule classe fornece métodos de construtor e destruidor protegidos e um método público Dispose . No final da solicitação, o Dispose método é chamado para excluir a instância da CHttpModuleclasse derivada de .

A CHttpModule classe também define os métodos específicos de notificação que o IIS 7 chama quando processa eventos no nível da solicitação dentro do pipeline de processamento de solicitação integrado. Um módulo HTTP pode se registrar para eventos específicos definindo uma lista de notificações na função RegisterModule exportada de um módulo.

Eventos de solicitação determinística

A maioria dos métodos de notificação no nível da solicitação é processada cronologicamente durante o fluxo normal de eventos no nível da solicitação dentro do pipeline integrado. Cada um dos métodos de notificação determinística no nível da solicitação tem uma notificação pós-evento correspondente, que permite que módulos HTTP sejam processados quando um evento ocorrer ou imediatamente após o evento ocorrer.

A tabela a seguir lista os métodos de notificação de evento no nível da solicitação cronológica e pós-evento na ordem de sua ocorrência dentro do pipeline integrado.

Método de notificação de evento	Método de notificação pós-evento
`OnBeginRequest`	`OnPostBeginRequest`
`OnAuthenticateRequest`	`OnPostAuthenticateRequest`
`OnAuthorizeRequest`	`OnPostAuthorizeRequest`
`OnResolveRequestCache`	`OnPostResolveRequestCache`
`OnMapRequestHandler`	`OnPostMapRequestHandler`
`OnAcquireRequestState`	`OnPostAcquireRequestState`
`OnPreExecuteRequestHandler`	`OnPostPreExecuteRequestHandler`
`OnExecuteRequestHandler`	`OnPostExecuteRequestHandler`
`OnReleaseRequestState`	`OnPostReleaseRequestState`
`OnUpdateRequestCache`	`OnPostUpdateRequestCache`
`OnLogRequest`	`OnPostLogRequest`
`OnEndRequest`	`OnPostEndRequest`

Por exemplo, OnBeginRequest ocorre antes OnAuthenticateRequestde , OnMapRequestHandler ocorrer antes OnAcquireRequestStatede e assim por diante.

Observação

As notificações pós-evento ocorrem antes da próxima notificação em nível de solicitação cronológica. Por exemplo, OnPostAuthenticateRequest ocorre antes OnAuthorizeRequestde , OnPostUpdateRequestCache ocorrer antes OnLogRequestde e assim por diante.

Eventos de solicitação não determinística

Os métodos de notificação de nível de solicitação restantes não são processados em nenhuma ordem específica; Em vez disso, o IIS processa esses eventos quando ocorre um evento não determinístico específico. A tabela a seguir lista o evento não determinístico no nível da solicitação e todos os métodos de notificação pós-evento relacionados.

Método de notificação de evento	Método de notificação pós-evento
`OnAsyncCompletion`	(Nenhum) ¹
`OnCustomRequestNotification`	(Nenhum) ²
`OnMapPath`	(Nenhuma)
`OnReadEntity`	(Nenhuma)
`OnSendResponse`	(Nenhuma)

¹ O OnAsyncCompletion método é chamado quando ocorre um evento assíncrono em um módulo HTTP. Dessa forma, você não pode se registrar para uma notificação assíncrona usando a função RegisterModule exportada de um módulo. Em vez disso, seu módulo forneceria um OnAsyncCompletion método para processar notificações que ocorrem após chamar métodos que retornam de forma assíncrona (por exemplo, os métodos IHttpContext::ExecuteRequest e IHttpResponse::WriteEntityChunks ). Quando o IIS chama OnAsyncCompletion, o método passará parâmetros que indicam o tipo de notificação e se a notificação foi para um evento ou pós-evento.

² O OnCustomRequestNotification método não tem um método de notificação pós-evento correspondente. Um módulo HTTP pode se registrar para uma notificação personalizada usando a função exportada RegisterModule do módulo, mas um módulo não pode se registrar para uma notificação que ocorre após a ocorrência de uma notificação personalizada.

Exemplo

O exemplo a seguir demonstra como criar um módulo HTTP "Olá, Mundo" simples. O módulo define uma função exportada RegisterModule que passa uma instância de uma IHttpModuleFactory interface para o método IHttpModuleRegistrationInfo::SetRequestNotifications e registra para a notificação de RQ_BEGIN_REQUEST . O IIS usa o método IHttpModuleFactory::GetHttpModule para criar uma instância de uma CHttpModule classe e retorna um status de êxito. O IIS também usa o método IHttpModuleFactory::Terminate para remover a fábrica da memória.

Quando ocorre uma RQ_BEGIN_REQUEST notificação, o IIS chama o método do OnBeginRequest módulo para processar a solicitação atual. OnBeginRequest limpa o buffer de resposta e modifica o tipo MIME para a resposta. Em seguida, o método cria uma parte de dados que contém uma cadeia de caracteres "Olá, Mundo" e retorna a cadeia de caracteres para um cliente Web. Por fim, o módulo retorna um indicador status que notifica o IIS de que todas as notificações foram concluídas e, em seguida, são encerradas.

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

Seu módulo deve exportar a RegisterModule função. Você pode exportar essa função criando um arquivo de definição de módulo (.def) para seu projeto ou pode compilar o módulo usando a opção /EXPORT:RegisterModule . Para obter mais informações, consulte Passo a passo: criando um módulo HTTP Request-Level usando código nativo.

Opcionalmente, você pode compilar o código usando a __stdcall (/Gz) convenção de chamada em vez de declarar explicitamente a convenção de chamada para cada função.

Requisitos

Type	Descrição
Cliente	– IIS 7.0 no Windows Vista – IIS 7.5 no Windows 7 – IIS 8.0 no Windows 8 – IIS 10.0 no Windows 10
Servidor	– IIS 7.0 no Windows Server 2008 – IIS 7.5 no Windows Server 2008 R2 – IIS 8.0 no Windows Server 2012 – IIS 8.5 no Windows Server 2012 R2 – IIS 10.0 no Windows Server 2016
Produto	- 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
parâmetro	Httpserv.h

Consulte Também

Criando módulos HTTP Native-Code
Classe CGlobalModule

Compartilhar via

Classe CHttpModule

Syntax

Métodos

Classes derivadas

Comentários

Eventos de solicitação determinística

Eventos de solicitação não determinística

Exemplo

Requisitos

Consulte Também

Comentários

Recursos adicionais