CHttpModule, classe

Article
07/19/2023

Définit la classe de base pour les modules HTTP au niveau de la requête.

Syntaxe

class CHttpModule

Méthodes

Le tableau suivant répertorie les méthodes exposées par la CHttpModule classe .

Nom	Description
~CHttpModule	Libère un instance de la `CHttpModule` classe .
CHttpModule	Initialise une nouvelle instance de la classe `CHttpModule`.
Dispose	Libère toutes les ressources utilisées par l'instance actuelle de la classe `CHttpModule`.
OnAcquireRequestState	Représente la méthode qui gère un `AcquireRequestState` événement, qui se produit quand IIS récupère l’état de la requête actuelle.
OnAsyncCompletion	Représente la méthode qui gère un événement d’achèvement asynchrone, qui se produit après la fin du traitement d’une opération asynchrone.
OnAuthenticateRequest	Représente la méthode qui gère un `AuthenticateRequest` événement, qui se produit quand IIS établit l’identité d’un utilisateur.
OnAuthorizeRequest	Représente la méthode qui gère un `AuthorizeRequest` événement, qui se produit quand IIS vérifie l’autorisation de l’utilisateur.
OnBeginRequest	Représente la méthode qui gère un `BeginRequest` événement, qui se produit en tant que premier événement dans le pipeline de traitement de requête intégré HTTP pour la requête actuelle.
OnCustomRequestNotification	Représente la méthode qui gère un événement personnalisé, qui se produit lorsqu’un module déclenche une notification définie par l’utilisateur.
OnEndRequest	Représente la méthode qui gérera un `EndRequest` événement, qui se produit en tant que dernier événement dans le pipeline de traitement de requête intégré HTTP pour la requête actuelle.
OnExecuteRequestHandler	Représente la méthode qui gère un `ExecuteRequestHandler` événement, qui se produit quand IIS exécute le gestionnaire pour la requête actuelle.
OnLogRequest	Représente la méthode qui gère un `LogRequest` événement, qui se produit quand IIS se prépare à journaliser la requête actuelle.
OnMapPath	Représente la méthode qui gère un `MapPath` événement, qui se produit lorsqu’une opération demande que le chemin physique soit mappé pour la requête actuelle.
OnMapRequestHandler	Représente la méthode qui gère un `MapRequestHandler` événement, qui se produit quand IIS mappe la requête actuelle à un gestionnaire d’événements.
OnPostAcquireRequestState	Représente la méthode qui gère un `AcquireRequestState` post-événement, qui se produit après qu’IIS a récupéré l’état de la requête actuelle.
OnPostAuthenticateRequest	Représente la méthode qui gérera un `AuthenticateRequest` post-événement, qui se produit après qu’IIS a établi l’identité d’un utilisateur.
OnPostAuthorizeRequest	Représente la méthode qui gère un `AuthorizeRequest` post-événement, qui se produit après qu’IIS a vérifié l’autorisation de l’utilisateur.
OnPostBeginRequest	Représente la méthode qui gérera un `BeginRequest` post-événement, qui se produit après le premier événement dans le pipeline de traitement de requête intégré HTTP.
OnPostEndRequest	Représente la méthode qui gère un `EndRequest` post-événement, qui se produit après le dernier événement dans le pipeline de traitement de requête intégré HTTP pour la requête actuelle.
OnPostExecuteRequestHandler	Représente la méthode qui gérera un `ExecuteRequestHandler` post-événement, qui se produit après qu’IIS a exécuté le gestionnaire pour la requête actuelle.
OnPostLogRequest	Représente la méthode qui gérera un `LogRequest` post-événement, qui se produit après qu’IIS a enregistré la requête actuelle.
OnPostMapRequestHandler	Représente la méthode qui gère un `MapRequestHandler` post-événement, qui se produit après qu’IIS a mappé la requête actuelle au gestionnaire d’événements approprié.
OnPostPreExecuteRequestHandler	Représente la méthode qui gère un `PreExecuteRequestHandler` post-événement, qui se produit avant qu’IIS exécute un gestionnaire de requêtes.
OnPostReleaseRequestState	Représente la méthode qui gérera un `ReleaseRequestState` post-événement, qui se produit après la publication de l’état actuel.
OnPostResolveRequestCache	Représente la méthode qui gérera un `ResolveRequestCache` post-événement, qui se produit après qu’IIS a résolu une demande à partir du cache.
OnPostUpdateRequestCache	Représente la méthode qui gère un `UpdateRequestCache` post-événement, qui se produit après qu’IIS a stocké la requête dans le cache.
OnPreExecuteRequestHandler	Représente la méthode qui gère un `PreExecuteRequestHandler` événement, qui se produit avant qu’IIS exécute un gestionnaire de requêtes.
OnReadEntity	Représente la méthode qui gérera un `ReadEntity` événement, qui se produit lorsqu’une opération lit des données à partir de la mémoire tampon de requête.
OnReleaseRequestState	Représente la méthode qui gérera un `ReleaseRequestState` événement, qui se produit lorsque l’état actuel est libéré.
OnResolveRequestCache	Représente la méthode qui gère un `ResolveRequestCache` événement, qui se produit quand IIS résout une demande dans le cache.
OnSendResponse	Représente la méthode qui gère un `SendResponse` événement, qui se produit quand IIS envoie la mémoire tampon de réponse.
OnUpdateRequestCache	Représente la méthode qui gère un `UpdateRequestCache` événement, qui se produit quand IIS stocke la requête dans le cache.

Classes dérivées

Cette classe ne contient aucune classe dérivée.

Remarques

La CHttpModule classe est la classe de base pour les modules HTTP au niveau de la requête. Pour créer une CHttpModuleclasse dérivée, vous devez créer un module HTTP au niveau de la requête qui contient une classe qui hérite de CHttpModule et une classe qui dérive de l’interface IHttpModuleFactory . Pour plus d’informations sur la création de modules HTTP, consultez Conception de modules HTTP Native-Code.

La CHttpModule classe fournit des méthodes de constructeur et de destructeur protégées et une méthode publique Dispose . À la fin de la demande, la Dispose méthode est appelée pour supprimer le instance de la CHttpModuleclasse dérivée .

La CHttpModule classe définit également les méthodes spécifiques aux notifications qu’IIS 7 appelle lorsqu’il traite des événements au niveau de la demande dans le pipeline intégré de traitement des demandes. Un module HTTP peut s’inscrire pour des événements spécifiques en définissant une liste de notifications dans la fonction RegisterModule exportée d’un module.

Événements de requête déterministes

La majorité des méthodes de notification au niveau de la demande sont traitées chronologiquement pendant le flux normal des événements au niveau de la demande au sein du pipeline intégré. Chacune des méthodes de notification déterministes au niveau de la demande a une notification post-événement correspondante, qui permet aux modules HTTP de traiter lorsqu’un événement se produit ou immédiatement après l’événement.

Le tableau suivant répertorie les méthodes chronologiques de notification au niveau de la demande et post-événement dans l’ordre de leur occurrence dans le pipeline intégré.

Méthode de notification d’événement	Méthode de notification post-événement
`OnBeginRequest`	`OnPostBeginRequest`
`OnAuthenticateRequest`	`OnPostAuthenticateRequest`
`OnAuthorizeRequest`	`OnPostAuthorizeRequest`
`OnResolveRequestCache`	`OnPostResolveRequestCache`
`OnMapRequestHandler`	`OnPostMapRequestHandler`
`OnAcquireRequestState`	`OnPostAcquireRequestState`
`OnPreExecuteRequestHandler`	`OnPostPreExecuteRequestHandler`
`OnExecuteRequestHandler`	`OnPostExecuteRequestHandler`
`OnReleaseRequestState`	`OnPostReleaseRequestState`
`OnUpdateRequestCache`	`OnPostUpdateRequestCache`
`OnLogRequest`	`OnPostLogRequest`
`OnEndRequest`	`OnPostEndRequest`

Par exemple, OnBeginRequest se produit avant OnAuthenticateRequest, OnMapRequestHandler se produit avant OnAcquireRequestState, et ainsi de suite.

Notes

Les notifications post-événement se produisent avant la prochaine notification chronologique au niveau de la demande. Par exemple, OnPostAuthenticateRequest se produit avant OnAuthorizeRequest, OnPostUpdateRequestCache se produit avant OnLogRequest, et ainsi de suite.

Événements de requête non déterministes

Les autres méthodes de notification au niveau de la demande ne sont pas traitées dans un ordre spécifique ; au lieu de cela, IIS traite ces événements lorsqu’un événement non déterministe spécifique se produit. Le tableau suivant répertorie l’événement de niveau requête non déterministe et toutes les méthodes de notification post-événement associées.

Méthode de notification d’événement	Méthode de notification post-événement
`OnAsyncCompletion`	(Aucun) ¹
`OnCustomRequestNotification`	(Aucun) ²
`OnMapPath`	(aucune)
`OnReadEntity`	(aucune)
`OnSendResponse`	(aucune)

¹ La OnAsyncCompletion méthode est appelée lorsqu’un événement asynchrone se produit dans un module HTTP. Par conséquent, vous ne pouvez pas inscrire une notification asynchrone à l’aide de la fonction RegisterModule exportée d’un module. Au lieu de cela, votre module fournit une OnAsyncCompletion méthode pour traiter les notifications qui se produisent après l’appel de méthodes qui retournent de manière asynchrone (par exemple, les méthodes IHttpContext::ExecuteRequest et IHttpResponse::WriteEntityChunks ). Quand IIS appelle OnAsyncCompletion, la méthode transmet des paramètres qui indiquent le type de notification et si la notification concerne un événement ou un post-événement.

² La OnCustomRequestNotification méthode n’a pas de méthode de notification post-événement correspondante. Un module HTTP peut s’inscrire à une notification personnalisée à l’aide de la fonction exportée RegisterModule du module, mais un module ne peut pas s’inscrire à une notification qui se produit après qu’une notification personnalisée s’est produite.

Exemple

L’exemple suivant montre comment créer un module HTTP « Hello World » simple. Le module définit une fonction exportée RegisterModule qui transmet une instance d’une IHttpModuleFactory interface à la méthode IHttpModuleRegistrationInfo::SetRequestNotifications et s’inscrit pour la notification RQ_BEGIN_REQUEST. IIS utilise la méthode IHttpModuleFactory::GetHttpModule pour créer un instance d’une CHttpModule classe et retourne une status de réussite. IIS utilise également la méthode IHttpModuleFactory::Terminate pour supprimer la fabrique de la mémoire.

Lorsqu’une RQ_BEGIN_REQUEST notification se produit, IIS appelle la méthode du OnBeginRequest module pour traiter la demande actuelle. OnBeginRequest efface la mémoire tampon de réponse et modifie le type MIME de la réponse. La méthode crée ensuite un segment de données qui contient une chaîne « Hello World » et retourne la chaîne à un client Web. Enfin, le module retourne un indicateur status qui avertit IIS que toutes les notifications sont terminées, puis se ferme.

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

Votre module doit exporter la RegisterModule fonction. Vous pouvez exporter cette fonction en créant un fichier de définition de module (.def) pour votre projet, ou vous pouvez compiler le module à l’aide du /EXPORT:RegisterModule commutateur. Pour plus d’informations, consultez Procédure pas à pas : création d’un module HTTP Request-Level à l’aide de code natif.

Vous pouvez éventuellement compiler le code à l’aide de la __stdcall (/Gz) convention d’appel au lieu de déclarer explicitement la convention d’appel pour chaque fonction.

Spécifications

Type	Description
Client	- IIS 7.0 sur Windows Vista - IIS 7.5 sur Windows 7 - IIS 8.0 sur Windows 8 - IIS 10.0 sur Windows 10
Serveur	- IIS 7.0 sur Windows Server 2008 - IIS 7.5 sur Windows Server 2008 R2 - IIS 8.0 sur Windows Server 2012 - IIS 8.5 sur Windows Server 2012 R2 - IIS 10.0 sur Windows Server 2016
Produit	- 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
En-tête	Httpserv.h

Voir aussi

Création de modules HTTP Native-Code
CGlobalModule, classe

Partager via