CHttpModule (clase)

Artículo
07/19/2023

Define la clase base para los módulos HTTP de nivel de solicitud.

Sintaxis

class CHttpModule

Métodos

En la tabla siguiente se enumeran los métodos expuestos por la CHttpModule clase .

Nombre	Descripción
~CHttpModule	Desasigna una instancia de la `CHttpModule` clase .
CHttpModule	Inicializa una nueva instancia de la clase `CHttpModule`.
Dispose	Libera todos los recursos usados por la instancia actual de la clase `CHttpModule`.
OnAcquireRequestState	Representa el método que controlará un `AcquireRequestState` evento, que se produce cuando IIS recupera el estado de la solicitud actual.
OnAsyncCompletion	Representa el método que controlará un evento de finalización asincrónica, que se produce después de que una operación asincrónica haya terminado de procesarse.
OnAuthenticateRequest	Representa el método que controlará un `AuthenticateRequest` evento, que se produce cuando IIS establece la identidad de un usuario.
OnAuthorizeRequest	Representa el método que controlará un `AuthorizeRequest` evento, que se produce cuando IIS comprueba la autorización del usuario.
OnBeginRequest	Representa el método que controlará un `BeginRequest` evento, que se produce como el primer evento de la canalización de procesamiento de solicitudes integrada HTTP para la solicitud actual.
OnCustomRequestNotification	Representa el método que controlará un evento personalizado, que se produce cuando un módulo genera una notificación definida por el usuario.
OnEndRequest	Representa el método que controlará un `EndRequest` evento, que se produce como el último evento de la canalización de procesamiento de solicitudes integrada HTTP para la solicitud actual.
OnExecuteRequestHandler	Representa el método que controlará un `ExecuteRequestHandler` evento, que se produce cuando IIS ejecuta el controlador para la solicitud actual.
OnLogRequest	Representa el método que controlará un `LogRequest` evento, que se produce cuando IIS se prepara para registrar la solicitud actual.
OnMapPath	Representa el método que controlará un `MapPath` evento, que se produce cuando una operación solicita que se asigne la ruta de acceso física para la solicitud actual.
OnMapRequestHandler	Representa el método que controlará un `MapRequestHandler` evento, que se produce cuando IIS asigna la solicitud actual a un controlador de eventos.
OnPostAcquireRequestState	Representa el método que controlará un `AcquireRequestState` evento posterior, que se produce después de que IIS haya recuperado el estado de la solicitud actual.
OnPostAuthenticateRequest	Representa el método que controlará un `AuthenticateRequest` evento posterior, que se produce después de que IIS haya establecido la identidad de un usuario.
OnPostAuthorizeRequest	Representa el método que controlará un `AuthorizeRequest` evento posterior, que se produce después de que IIS haya comprobado la autorización del usuario.
OnPostBeginRequest	Representa el método que controlará un `BeginRequest` evento posterior, que se produce después del primer evento de la canalización de procesamiento de solicitudes integrada HTTP.
OnPostEndRequest	Representa el método que controlará un `EndRequest` evento posterior, que se produce después del último evento en la canalización de procesamiento de solicitudes integrada HTTP para la solicitud actual.
OnPostExecuteRequestHandler	Representa el método que controlará un `ExecuteRequestHandler` evento posterior, que se produce después de que IIS ejecute el controlador para la solicitud actual.
OnPostLogRequest	Representa el método que controlará un `LogRequest` evento posterior, que se produce después de que IIS haya registrado la solicitud actual.
OnPostMapRequestHandler	Representa el método que controlará un `MapRequestHandler` evento posterior, que se produce después de que IIS haya asignado la solicitud actual al controlador de eventos adecuado.
OnPostPreExecuteRequestHandler	Representa el método que controlará un `PreExecuteRequestHandler` evento posterior, que se produce antes de que IIS ejecute un controlador de solicitudes.
OnPostReleaseRequestState	Representa el método que controlará un `ReleaseRequestState` evento posterior, que se produce después de que se haya liberado el estado actual.
OnPostResolveRequestCache	Representa el método que controlará un `ResolveRequestCache` evento posterior, que se produce después de que IIS haya resuelto una solicitud de la memoria caché.
OnPostUpdateRequestCache	Representa el método que controlará un `UpdateRequestCache` evento posterior, que se produce después de que IIS haya almacenado la solicitud en la memoria caché.
OnPreExecuteRequestHandler	Representa el método que controlará un `PreExecuteRequestHandler` evento, que se produce antes de que IIS ejecute un controlador de solicitudes.
OnReadEntity	Representa el método que controlará un `ReadEntity` evento, que se produce cuando una operación lee datos del búfer de solicitudes.
OnReleaseRequestState	Representa el método que controlará un `ReleaseRequestState` evento, que se produce cuando se libera el estado actual.
OnResolveRequestCache	Representa el método que controlará un `ResolveRequestCache` evento, que se produce cuando IIS resuelve una solicitud en la memoria caché.
OnSendResponse	Representa el método que controlará un `SendResponse` evento, que se produce cuando IIS envía el búfer de respuesta.
OnUpdateRequestCache	Representa el método que controlará un `UpdateRequestCache` evento, que se produce cuando IIS almacena la solicitud en la memoria caché.

Clases derivadas

Esta clase no contiene clases derivadas.

Comentarios

La CHttpModule clase es la clase base para los módulos HTTP de nivel de solicitud. Para crear una CHttpModuleclase derivada, debe crear un módulo HTTP de nivel de solicitud que contenga una clase que herede de CHttpModule y una clase que derive de la interfaz IHttpModuleFactory . Para obtener más información sobre cómo crear módulos HTTP, consulte Diseño de Native-Code módulos HTTP.

La CHttpModule clase proporciona métodos de constructor y destructor protegidos y un método público Dispose . Al final de la solicitud, Dispose se llama al método para eliminar la instancia de la CHttpModuleclase derivada de .

La CHttpModule clase también define los métodos específicos de la notificación a los que IIS 7 llama cuando procesa eventos de nivel de solicitud dentro de la canalización integrada de procesamiento de solicitudes. Un módulo HTTP puede registrarse para eventos específicos mediante la definición de una lista de notificaciones en la función RegisterModule exportada de un módulo.

Eventos de solicitud deterministas

La mayoría de los métodos de notificación de nivel de solicitud se procesan cronológicamente durante el flujo normal de eventos de nivel de solicitud dentro de la canalización integrada. Cada uno de los métodos de notificación de nivel de solicitud deterministas tiene una notificación posterior a eventos coincidente, que permite a los módulos HTTP procesar cuándo se produce un evento o inmediatamente después de que se produzca el evento.

En la tabla siguiente se enumeran los métodos cronológicos de notificación de nivel de solicitud y posteriores al evento en el orden de su aparición dentro de la canalización integrada.

Método de notificación de eventos	Método de notificación posterior al 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 ejemplo, se produce antes de OnBeginRequest , OnMapRequestHandler se produce antes OnAuthenticateRequestOnAcquireRequestStatede , etc.

Nota

Las notificaciones posteriores a los eventos se producen antes de la siguiente notificación cronológica de nivel de solicitud. Por ejemplo, se produce antes de OnPostAuthenticateRequest , OnPostUpdateRequestCache se produce antes OnAuthorizeRequestOnLogRequestde , etc.

Eventos de solicitud no deterministas

Los métodos de notificación de nivel de solicitud restantes no se procesan en ningún orden específico; en su lugar, IIS procesa estos eventos cuando se produce un evento no determinista específico. En la tabla siguiente se enumeran los eventos de nivel de solicitud no deterministas y los métodos de notificación posteriores a eventos relacionados.

Método de notificación de eventos	Método de notificación posterior al evento
`OnAsyncCompletion`	(Ninguno) ¹
`OnCustomRequestNotification`	(Ninguno) ²
`OnMapPath`	(Ninguna)
`OnReadEntity`	(Ninguna)
`OnSendResponse`	(Ninguna)

¹ Se OnAsyncCompletion llama al método cuando se produce un evento asincrónico dentro de un módulo HTTP. Por lo tanto, no se puede registrar para una notificación asincrónica mediante la función RegisterModule exportada de un módulo. En su lugar, el módulo proporcionaría un OnAsyncCompletion método para procesar las notificaciones que se producen después de llamar a métodos que devuelven de forma asincrónica (por ejemplo, los métodos IHttpContext::ExecuteRequest e IHttpResponse::WriteEntityChunks ). Cuando IIS llama a OnAsyncCompletion, el método pasará parámetros que indican el tipo de notificación y si la notificación era para un evento o posterior.

² El OnCustomRequestNotification método no tiene un método de notificación posterior al evento correspondiente. Un módulo HTTP puede registrarse para una notificación personalizada mediante la función exportada RegisterModule del módulo, pero un módulo no puede registrarse para una notificación que se produce después de que se haya producido una notificación personalizada.

Ejemplo

En el ejemplo siguiente se muestra cómo crear un módulo HTTP sencillo de "Hola mundo". El módulo define una función exportada RegisterModule que pasa una instancia de una IHttpModuleFactory interfaz al método IHttpModuleRegistrationInfo::SetRequestNotifications y registra la notificación de RQ_BEGIN_REQUEST . IIS usa el método IHttpModuleFactory::GetHttpModule para crear una instancia de una CHttpModule clase y devuelve un estado correcto. IIS también usa el método IHttpModuleFactory::Terminate para quitar el generador de la memoria.

Cuando se produce una RQ_BEGIN_REQUEST notificación, IIS llama al método del OnBeginRequest módulo para procesar la solicitud actual. OnBeginRequest borra el búfer de respuesta y modifica el tipo MIME para la respuesta. A continuación, el método crea un fragmento de datos que contiene una cadena "Hola mundo" y devuelve la cadena a un cliente web. Por último, el módulo devuelve un indicador de estado que notifica a IIS que todas las notificaciones han finalizado y, a continuación, se cierran.

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

El módulo debe exportar la RegisterModule función. Puede exportar esta función mediante la creación de un archivo de definición de módulo (.def) para el proyecto, o bien puede compilar el módulo mediante el /EXPORT:RegisterModule modificador . Para obtener más información, vea Tutorial: Creación de un módulo HTTP de Request-Level mediante código nativo.

Opcionalmente, puede compilar el código mediante la __stdcall (/Gz) convención de llamada en lugar de declarar explícitamente la convención de llamada para cada función.

Requisitos

Tipo	Descripción
Remoto	- IIS 7.0 en Windows Vista - IIS 7.5 en Windows 7 - IIS 8.0 en Windows 8 - IIS 10.0 en Windows 10
Servidor	- IIS 7.0 en Windows Server 2008 - IIS 7.5 en Windows Server 2008 R2 - IIS 8.0 en Windows Server 2012 - IIS 8.5 en Windows Server 2012 R2 - IIS 10.0 en Windows Server 2016
Producto	- 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
Encabezado	Httpserv.h

Consulte también

Creación de módulos HTTP de Native-Code
CGlobalModule (clase)

Compartir a través de

CHttpModule (clase)

Sintaxis

Métodos

Clases derivadas

Comentarios

Eventos de solicitud deterministas

Eventos de solicitud no deterministas

Ejemplo

Requisitos

Consulte también

Comentarios

Recursos adicionales