Compartilhar via

Função PFN_REGISTERMODULE

Define o protótipo de RegisterModule função para módulos HTTP de código nativo.

Sintaxe

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

Parâmetros

dwServerVersion
Um DWORD que contém o número de versão principal do IIS.

pModuleInfo
Um ponteiro para uma interface IHttpModuleRegistrationInfo .

pGlobalInfo
Um ponteiro para uma interface IHttpServer .

Valor Retornado

Um HRESULT. Os possíveis valores incluem, mas sem limitação, aqueles na tabela a seguir.

Valor Descrição
S_OK Indica que a operação foi bem-sucedida.

Observação

Seu módulo pode retornar qualquer valor válido HRESULT , mas deve retornar pelo menos S_OK para indicar que sua RegisterModule função foi bem-sucedida.

Comentários

PFN_REGISTERMODULE é um protótipo de função para a RegisterModule função que todos os módulos HTTP são necessários para implementar para o ponto de entrada da DLL.

Quando você cria um módulo HTTP, seu módulo precisa adicionar o seguinte RegisterModule método:

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

Todos os módulos HTTP devem exportar sua RegisterModule função para que o IIS carregue o módulo. Você pode exportar a RegisterModule função criando um arquivo de definição de módulo (.def) para seu projeto de DLL ou compilando o módulo usando a opção /EXPORT:RegisterModule .

Sua RegisterModule função precisará usar a IHttpModuleRegistrationInfo interface para registrar notificações usando os métodos SetRequestNotifications e SetGlobalNotifications . RegisterModule também precisará usar IHttpModuleRegistrationInfo para registrar prioridades de módulo usando os métodos SetPriorityForRequestNotification e SetPriorityForGlobalNotification .

O dwServerVersion parâmetro contém o número de versão principal para a versão do IIS que carrega o módulo. Por exemplo, para o IIS 7.0, o dwServerVersion parâmetro conterá um 7.

Quando o IIS chama sua RegisterModule função, ela fornece uma IHttpServer interface, que seu módulo pode usar para recuperar informações de nível de servidor.

Observação

Os eventos de rastreamento não devem ser gerados (por meio do Método IHttpTraceContext::QuickTrace ou qualquer outro meio por meio do Método IHttpServer::GetTraceContext) dentro da implementação da RegisterModule função. Gerar eventos de rastreamento dentro do RegisterModule pode causar uma violação de acesso, pois é muito cedo no pipeline de solicitação.

Exemplo

O exemplo de código 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 interface IHttpModuleFactory para o método IHttpModuleRegistrationInfo::SetRequestNotifications e se registra para a notificação de RQ_BEGIN_REQUEST . O IIS usa o método IHttpModuleFactory::GetHttpModule para criar uma instância de uma classe CHttpModule e retorna um sucesso status. 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 CHttpModule::OnBeginRequest do 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

IHttpModuleRegistrationInfo Interface
Método IHttpModuleRegistrationInfo::SetGlobalNotifications
Método IHttpModuleRegistrationInfo::SetPriorityForGlobalNotification
Método IHttpModuleRegistrationInfo::SetPriorityForRequestNotification
Método IHttpModuleRegistrationInfo::SetRequestNotifications
IHttpServer Interface

  • Last updated on