Classe CHttpModule

Articolo
07/19/2023

Definisce la classe di base per i moduli HTTP a livello di richiesta.

Sintassi

class CHttpModule

Metodi

Nella tabella seguente sono elencati i metodi esposti dalla CHttpModule classe .

Nome	Descrizione
~CHttpModule	Dealloca un'istanza della `CHttpModule` classe.
CHttpModule	Inizializza una nuova istanza della classe `CHttpModule`.
Dispose	Rilascia tutte le risorse usate dall'istanza corrente della classe `CHttpModule`.
OnAcquireRequestState	Rappresenta il metodo che gestirà un `AcquireRequestState` evento, che si verifica quando IIS recupera lo stato per la richiesta corrente.
OnAsyncCompletion	Rappresenta il metodo che gestirà un evento di completamento asincrono, che si verifica dopo la fine dell'elaborazione di un'operazione asincrona.
OnAuthenticateRequest	Rappresenta il metodo che gestirà un `AuthenticateRequest` evento, che si verifica quando IIS stabilisce l'identità di un utente.
OnAuthorizeRequest	Rappresenta il metodo che gestirà un `AuthorizeRequest` evento, che si verifica quando IIS verifica l'autorizzazione utente.
OnBeginRequest	Rappresenta il metodo che gestirà un `BeginRequest` evento, che si verifica come primo evento nella pipeline di elaborazione integrata della richiesta HTTP per la richiesta corrente.
OnCustomRequestNotification	Rappresenta il metodo che gestirà un evento personalizzato, che si verifica quando un modulo genera una notifica definita dall'utente.
OnEndRequest	Rappresenta il metodo che gestirà un `EndRequest` evento, che si verifica come ultimo evento nella pipeline di elaborazione integrata della richiesta HTTP per la richiesta corrente.
OnExecuteRequestHandler	Rappresenta il metodo che gestirà un `ExecuteRequestHandler` evento, che si verifica quando IIS esegue il gestore per la richiesta corrente.
OnLogRequest	Rappresenta il metodo che gestirà un `LogRequest` evento, che si verifica quando IIS prepara per registrare la richiesta corrente.
OnMapPath	Rappresenta il metodo che gestirà un `MapPath` evento, che si verifica quando un'operazione richiede il mapping del percorso fisico per la richiesta corrente.
OnMapRequestHandler	Rappresenta il metodo che gestirà un `MapRequestHandler` evento, che si verifica quando IIS esegue il mapping della richiesta corrente a un gestore eventi.
OnPostAcquireRequestState	Rappresenta il metodo che gestirà un `AcquireRequestState` evento post-evento, che si verifica dopo che IIS ha recuperato lo stato per la richiesta corrente.
OnPostAuthenticateRequest	Rappresenta il metodo che gestirà un `AuthenticateRequest` evento post-evento, che si verifica dopo che IIS ha stabilito l'identità di un utente.
OnPostAuthorizeRequest	Rappresenta il metodo che gestirà un `AuthorizeRequest` evento post-evento, che si verifica dopo che IIS ha verificato l'autorizzazione utente.
OnPostBeginRequest	Rappresenta il metodo che gestirà un `BeginRequest` evento post-evento, che si verifica dopo il primo evento nella pipeline di elaborazione integrata della richiesta HTTP.
OnPostEndRequest	Rappresenta il metodo che gestirà un `EndRequest` evento post-evento, che si verifica dopo l'ultimo evento nella pipeline di elaborazione integrata della richiesta HTTP per la richiesta corrente.
OnPostExecuteRequestHandler	Rappresenta il metodo che gestirà un `ExecuteRequestHandler` evento post-evento, che si verifica dopo l'esecuzione di IIS del gestore per la richiesta corrente.
OnPostLogRequest	Rappresenta il metodo che gestirà un `LogRequest` evento post-evento, che si verifica dopo che IIS ha registrato la richiesta corrente.
OnPostMapRequestHandler	Rappresenta il metodo che gestirà un `MapRequestHandler` evento post-evento, che si verifica dopo il mapping della richiesta corrente al gestore eventi appropriato.
OnPostPreExecuteRequestHandler	Rappresenta il metodo che gestirà un `PreExecuteRequestHandler` evento post-evento, che si verifica prima che IIS esebri un gestore della richiesta.
OnPostReleaseRequestState	Rappresenta il metodo che gestirà un `ReleaseRequestState` evento post-evento, che si verifica dopo il rilascio dello stato corrente.
OnPostResolveRequestCache	Rappresenta il metodo che gestirà un `ResolveRequestCache` evento post-evento, che si verifica dopo che IIS ha risolto una richiesta dalla cache.
OnPostUpdateRequestCache	Rappresenta il metodo che gestirà un `UpdateRequestCache` evento post-evento, che si verifica dopo che IIS ha archiviato la richiesta nella cache.
OnPreExecuteRequestHandler	Rappresenta il metodo che gestirà un `PreExecuteRequestHandler` evento, che si verifica prima che IIS esebri un gestore della richiesta.
OnReadEntity	Rappresenta il metodo che gestirà un `ReadEntity` evento, che si verifica quando un'operazione legge i dati dal buffer della richiesta.
OnReleaseRequestState	Rappresenta il metodo che gestirà un `ReleaseRequestState` evento, che si verifica quando viene rilasciato lo stato corrente.
OnResolveRequestCache	Rappresenta il metodo che gestirà un `ResolveRequestCache` evento, che si verifica quando IIS risolve una richiesta nella cache.
OnSendResponse	Rappresenta il metodo che gestirà un `SendResponse` evento, che si verifica quando IIS invia il buffer di risposta.
OnUpdateRequestCache	Rappresenta il metodo che gestirà un `UpdateRequestCache` evento, che si verifica quando IIS archivia la richiesta nella cache.

Classi derivate

Questa classe non contiene classi derivate.

Commenti

La CHttpModule classe è la classe di base per i moduli HTTP a livello di richiesta. Per creare una classe derivata da -, è necessario creare un modulo HTTP a livello di richiesta che contiene una CHttpModuleclasse che eredita da CHttpModule e una classe che deriva dall'interfaccia IHttpModuleFactory . Per altre informazioni sulla creazione di moduli HTTP, vedere Progettazione di moduli HTTP Native-Code.

La CHttpModule classe fornisce metodi di costruttore e distruttori protetti e un metodo pubblico Dispose . Alla fine della richiesta, il Dispose metodo viene chiamato per eliminare l'istanza della CHttpModuleclasse derivata.

La CHttpModule classe definisce anche i metodi specifici della notifica che IIS 7 chiama quando elabora eventi a livello di richiesta all'interno della pipeline integrata di elaborazione delle richieste. Un modulo HTTP può registrarsi per eventi specifici definendo un elenco di notifiche nella funzione RegisterModule esportata di un modulo.

Eventi di richiesta deterministica

La maggior parte dei metodi di notifica a livello di richiesta viene elaborata cronologicamente durante il normale flusso di eventi a livello di richiesta all'interno della pipeline integrata. Ognuno dei metodi di notifica a livello di richiesta deterministica ha una notifica post-evento corrispondente, che consente ai moduli HTTP di elaborare quando si verifica un evento o immediatamente dopo l'evento.

Nella tabella seguente sono elencati i metodi cronologici di notifica a livello di richiesta e post-evento nell'ordine della loro occorrenza all'interno della pipeline integrata.

Metodo di notifica eventi	Metodo di notifica post-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`

Ad esempio, si verifica prima di OnBeginRequest , OnMapRequestHandler si verifica prima OnAuthenticateRequestOnAcquireRequestStatedi e così via.

Nota

Le notifiche post-evento si verificano prima della notifica a livello di richiesta cronologica successiva. Ad esempio, si verifica prima di OnPostAuthenticateRequest , OnPostUpdateRequestCache si verifica prima OnAuthorizeRequestOnLogRequestdi e così via.

Eventi di richiesta non deterministica

I metodi di notifica a livello di richiesta rimanenti non vengono elaborati in alcun ordine specifico; IIS elabora invece questi eventi quando si verifica un evento non terministico specifico. La tabella seguente elenca l'evento a livello di richiesta non terministico e i metodi di notifica post-evento correlati.

Metodo di notifica eventi	Metodo di notifica post-evento
`OnAsyncCompletion`	(Nessuno) ¹
`OnCustomRequestNotification`	(Nessuno) ²
`OnMapPath`	(nessuna)
`OnReadEntity`	(nessuna)
`OnSendResponse`	(nessuna)

¹ Il OnAsyncCompletion metodo viene chiamato quando si verifica un evento asincrono all'interno di un modulo HTTP. Di conseguenza, non è possibile registrare per una notifica asincrona usando la funzione RegisterModule esportata di un modulo. Il modulo fornisce invece un OnAsyncCompletion metodo per elaborare le notifiche che si verificano dopo la chiamata di metodi che restituiscono in modo asincrono i metodi IHttpContext::ExecuteRequest e IHttpResponse::WriteEntityChunks . Quando IIS chiama OnAsyncCompletion, il metodo passerà i parametri che indicano il tipo di notifica e se la notifica era per un evento o un evento post-evento.

² Il OnCustomRequestNotification metodo non ha un metodo di notifica post-evento corrispondente. Un modulo HTTP può registrarsi per una notifica personalizzata usando la funzione esportata RegisterModule del modulo, ma non è possibile registrare un modulo per una notifica che si verifica dopo che si è verificata una notifica personalizzata.

Esempio

Nell'esempio seguente viene illustrato come creare un semplice modulo HTTP "Hello World". Il modulo definisce una funzione esportata RegisterModule che passa un'istanza di un'interfaccia IHttpModuleFactory al metodo IHttpModuleRegistrationInfo::SetRequestNotifications e registra per la notifica di RQ_BEGIN_REQUEST . IIS usa il metodo IHttpModuleFactory::GetHttpModule per creare un'istanza di una CHttpModule classe e restituisce uno stato di esito positivo. IIS usa anche il metodo IHttpModuleFactory::Terminate per rimuovere la factory dalla memoria.

Quando si verifica una RQ_BEGIN_REQUEST notifica, IIS chiama il metodo del OnBeginRequest modulo per elaborare la richiesta corrente. OnBeginRequest cancella il buffer di risposta e modifica il tipo MIME per la risposta. Il metodo crea quindi un blocco di dati che contiene una stringa "Hello World" e restituisce la stringa a un client Web. Infine, il modulo restituisce un indicatore di stato che notifica a IIS che tutte le notifiche vengono completate e quindi terminano.

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

Il modulo deve esportare la RegisterModule funzione. È possibile esportare questa funzione creando un file di definizione del modulo (con estensione def) per il progetto oppure è possibile compilare il modulo usando l'opzione /EXPORT:RegisterModule . Per altre informazioni, vedere Procedura dettagliata: Creazione di un modulo HTTP Request-Level tramite codice nativo.

Facoltativamente, è possibile compilare il codice usando la __stdcall (/Gz) convenzione chiamante anziché dichiarare esplicitamente la convenzione chiamante per ogni funzione.

Requisiti

Tipo	Descrizione
Client	- IIS 7.0 in Windows Vista - IIS 7.5 in Windows 7 - IIS 8.0 in Windows 8 - IIS 10.0 in Windows 10
Server	- IIS 7.0 in Windows Server 2008 - IIS 7.5 in Windows Server 2008 R2 - IIS 8.0 in Windows Server 2012 - IIS 8.5 in Windows Server 2012 R2 - IIS 10.0 in Windows Server 2016
Prodotto	- 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
Intestazione	Httpserv.h

Vedere anche

Creazione di moduli HTTP Native-Code
Classe CGlobalModule

Condividi tramite