CHttpModule::OnAsyncCompletion, méthode

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.

Syntaxe

virtual REQUEST_NOTIFICATION_STATUS OnAsyncCompletion(  
   IN IHttpContext* pHttpContext,  
   IN DWORD dwNotification,  
   IN BOOL fPostNotification,  
   IN OUT IHttpEventProvider* pProvider,  
   IN IHttpCompletionInfo* pCompletionInfo  
);  

Paramètres

pHttpContext
[IN] Pointeur vers une interface IHttpContext .

dwNotification
[IN] Valeur DWORD qui contient le masque de bits de la notification associée.

fPostNotification
[IN] true pour indiquer que la notification concerne un post-événement ; sinon, false.

pProvider
[IN] Pointeur vers une interface IHttpEventProvider .

pCompletionInfo
[IN] Pointeur vers une interface IHttpCompletionInfo .

Valeur renvoyée

Valeur REQUEST_NOTIFICATION_STATUS .

Remarques

Contrairement à la plupart des autres méthodes CHttpModule appelées en s’inscrivant pour des notifications spécifiques, IIS appelle la méthode d’un OnAsyncCompletion module uniquement lorsqu’une opération asynchrone est terminée. Par exemple, lorsqu’un module au niveau de la demande appelle la méthode IHttpResponse::WriteEntityChunks et spécifie l’achèvement asynchrone, IIS appelle la méthode du OnAsyncCompletion module une fois l’opération terminée.

Quand IIS appelle la OnAsyncCompletion méthode, il spécifie le type de notification dans le dwNotification paramètre et indique si la notification concerne un événement ou un post-événement à l’aide du fPostNotification paramètre . IIS fournit également une IHttpCompletionInfo interface vers laquelle pointe le pCompletionInfo paramètre . Vous pouvez utiliser cette interface pour récupérer des informations supplémentaires sur l’achèvement asynchrone.

Exemple

L’exemple de code suivant montre comment créer un module HTTP qui effectue les tâches suivantes :

1. Le module s’inscrit aux notifications RQ_BEGIN_REQUEST et RQ_MAP_REQUEST_HANDLER .

2. Le module crée une CHttpModule classe qui contient OnBeginRequest, OnMapRequestHandler et OnAsyncCompletion les méthodes.

3. Lorsqu’un client Web demande une URL, IIS appelle la méthode du OnBeginRequest module. Cette méthode effectue les tâches suivantes :

   1. Efface la mémoire tampon de réponse existante et définit le type MIME pour la réponse.

   2. Crée un exemple de chaîne et le retourne au client Web de manière asynchrone.

   3. Teste une erreur ou une complétion asynchrone. Si l’achèvement asynchrone est en attente, le module retourne une notification en attente status au pipeline de traitement des demandes intégré.

4. IIS appelle la méthode du OnMapRequestHandler module. Cette méthode effectue les tâches suivantes :

   1. Vide la mémoire tampon de réponse actuelle sur le client Web.

   2. Teste une erreur ou une complétion asynchrone. Si l’achèvement asynchrone est en attente, le module retourne une notification en attente status au pipeline.

5. Si la saisie semi-automatique est requise, IIS appelle la méthode du OnAsyncCompletion module. Cette méthode effectue les tâches suivantes :

   1. Teste une interface valide IHttpCompletionInfo . Si une interface valide IHttpCompletionInfo a été passée, la méthode appelle les méthodes GetCompletionBytes et GetCompletionStatus, respectivement, pour récupérer les octets terminés et retourner les status pour l’opération asynchrone.

   2. Crée des chaînes qui contiennent les informations d’achèvement et écrit les informations en tant qu’événement dans le journal des applications de l’observateur d'événements.

6. Le module supprime la classe de la CHttpModule mémoire, puis se ferme.

#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <httpserv.h>
#include <wchar.h>

// Create the module class.
class MyHttpModule : 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;
        // Buffer to store the byte count.
        DWORD cbSent = 0;
        // Buffer to store if asyncronous completion is pending.
        BOOL fCompletionExpected = false;
        // Create an example string to return to the Web client.
        char szBuffer[] = "Hello World!";
        
        // Clear the existing response.
        pHttpContext->GetResponse()->Clear();
        // Set the MIME type to plain text.
        pHttpContext->GetResponse()->SetHeader(
            HttpHeaderContentType,"text/plain",
            (USHORT)strlen("text/plain"),TRUE);
        
        // Create a data chunk.
        HTTP_DATA_CHUNK dataChunk;
        // Set the chunk to a chunk in memory.
        dataChunk.DataChunkType = HttpDataChunkFromMemory;
        // Set the chunk to the buffer.
        dataChunk.FromMemory.pBuffer =
            (PVOID) szBuffer;
        // Set the chunk size to the buffer size.
        dataChunk.FromMemory.BufferLength =
            (USHORT) strlen(szBuffer);
        // Insert the data chunk into the response.
        hr = pHttpContext->GetResponse()->WriteEntityChunks(
            &dataChunk,1,TRUE,TRUE,&cbSent,&fCompletionExpected);

        // Test for a failure.
        if (FAILED(hr))
        {
            // Set the HTTP status.
            pHttpContext->GetResponse()->SetStatus(
                500,"Server Error",0,hr);
            // End additional processing.
            return RQ_NOTIFICATION_FINISH_REQUEST;
        }
        
        // Test for pending asynchronous operations.
        if (fCompletionExpected)
        {
            return RQ_NOTIFICATION_PENDING;
        }

        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }
    
    REQUEST_NOTIFICATION_STATUS
    OnMapRequestHandler(
        IN IHttpContext * pHttpContext,
        IN IMapHandlerProvider * pProvider
    )
    {
        // Create an HRESULT to receive return values from methods.
        HRESULT hr;
        // Buffer to store the byte count.
        DWORD cbSent = 0;
        // Buffer to store if asyncronous completion is pending.
        BOOL fCompletionExpected = false;

        // Flush the response to the client.
        hr = pHttpContext->GetResponse()->Flush(
            TRUE,FALSE,&cbSent,&fCompletionExpected);

        // Test for a failure.
        if (FAILED(hr))
        {
            // Set the HTTP status.
            pHttpContext->GetResponse()->SetStatus(
                500,"Server Error",0,hr);
        }

        // Test for pending asynchronous operations.
        if (fCompletionExpected)
        {
            return RQ_NOTIFICATION_PENDING;
        }

        // End additional processing.
        return RQ_NOTIFICATION_CONTINUE;
    }

    REQUEST_NOTIFICATION_STATUS
        OnAsyncCompletion(
        IN IHttpContext * pHttpContext,
        IN DWORD dwNotification,
        IN BOOL fPostNotification,
        IN IHttpEventProvider * pProvider,
        IN IHttpCompletionInfo * pCompletionInfo
        )
    {        
        if ( NULL != pCompletionInfo )
        {
            // Create strings for completion information.
            char szNotification[256] = "";
            char szBytes[256] = "";
            char szStatus[256] = "";

            // Retrieve and format the completion information.
            sprintf_s(szNotification,255,"Notification: %u",
                dwNotification);
            sprintf_s(szBytes,255,"Completion Bytes: %u",
                pCompletionInfo->GetCompletionBytes());
            sprintf_s(szStatus,255,"Completion Status: 0x%08x",
                pCompletionInfo->GetCompletionStatus());

            // Create an array of strings.
            LPCSTR szBuffer[3] = {szNotification,szBytes,szStatus};
            // Write the strings to the Event Viewer.
            WriteEventViewerLog(szBuffer,3);
        }
        
        // Return processing to the pipeline.
        return RQ_NOTIFICATION_CONTINUE;
    }

    MyHttpModule(void)
    {
        // Open a handle to the Event Viewer.
        m_hEventLog = RegisterEventSource( NULL,"IISADMIN" );
    }

    ~MyHttpModule(void)
    {
        // Test if the handle for the Event Viewer is open.
        if (NULL != m_hEventLog)
        {
            // Close the handle to the Event Viewer.
            DeregisterEventSource( m_hEventLog );
            m_hEventLog = NULL;
        }
    }

private:

    // Handle for the Event Viewer.
    HANDLE m_hEventLog;

    // Define a method that writes to the Event Viewer.
    BOOL WriteEventViewerLog(LPCSTR * lpStrings, WORD wNumStrings)
    {
        // Test whether the handle for the Event Viewer is open.
        if (NULL != m_hEventLog)
        {
            // Write any strings to the Event Viewer and return.
            return ReportEvent(
                m_hEventLog, EVENTLOG_INFORMATION_TYPE,
                0, 0, NULL, wNumStrings, 0, lpStrings, NULL );
        }
        return FALSE;
    }
};

// Create the module's class factory.
class MyHttpModuleFactory : public IHttpModuleFactory
{
public:
    HRESULT
    GetHttpModule(
        OUT CHttpModule ** ppModule, 
        IN IModuleAllocator * pAllocator
    )
    {
        UNREFERENCED_PARAMETER( pAllocator );

        // Create a new instance.
        MyHttpModule * pModule = new MyHttpModule;

        // Test for an error.
        if (!pModule)
        {
            // Return an error if we 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 );

    return pModuleInfo->SetRequestNotifications(
        new MyHttpModuleFactory,
        RQ_BEGIN_REQUEST | RQ_MAP_REQUEST_HANDLER,
        0
    );
}

Votre module doit exporter la fonction RegisterModule . 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

Voir aussi

CHttpModule, classe