Metodo IHttpModuleContextContainer::SetModuleContext
Imposta il contesto archiviato nel contenitore di contesto.
Sintassi
virtual HRESULT SetModuleContext(
IN IHttpStoredContext* ppStoredContext,
IN HTTP_MODULE_ID moduleId
) = 0;
Parametri
ppStoredContext
[IN] Puntatore a un valore IHttpStoredContext . Deve essere diverso da NULL.
moduleId
[IN] Puntatore HTTP_MODULE_ID .
Nota
HTTP_MODULE_ID è una definizione di tipo di un void puntatore.
Valore restituito
Oggetto HRESULT. I valori possibili includono, ma non sono limitati a, quelli indicati nella tabella seguente.
| valore | Definizione |
|---|---|
| NO_ERROR | Indica che l'operazione è riuscita. |
| ERROR_INVALID_PARAMETER | Indica che ppStoredContext è NULL. |
| ERROR_NOT_ENOUGH_MEMORY | Indica che la memoria dell'heap è esaurita. |
| ERROR_ALREADY_ASSIGNED | Indica che SetModuleContext è stato chiamato in precedenza. |
Commenti
I puntatori CGlobalModule o CHttpModule vengono registrati per vari eventi definiti nel file di intestazione Httpserv.h. Per altre informazioni, vedere Costanti di elaborazione delle richieste. Tramite uno di questi metodi delle virtual classi, è possibile recuperare i puntatori IHttpModuleContextContainer da varie interfacce che implementano un GetModuleContextContainer metodo.
È possibile definire classi personalizzate che implementano l'interfaccia IHttpStoredContext e quindi creare un puntatore a questo IHttpStoredContext implementatore di classe chiamando l'operatore new . È quindi possibile aggiungere e recuperare questo puntatore in un IHttpModuleContextContainer puntatore chiamando rispettivamente i SetModuleContext metodi e GetModuleContext .
Quando il IHttpStoredContext puntatore non è più necessario, il metodo IHttpStoredContext::CleanupStoredContext viene chiamato internamente, in cui l'implementatore del IHttpStoredContext metodo di interfaccia deve in genere chiamare delete``this.
Note per gli implementatori
Gli implementatori IHttpModuleContextContainer sono responsabili della gestione della memoria con questi dati; pertanto, IHttpModuleContextContainer gli implementatori che usano l'allocazione dinamica della memoria devono rilasciare o chiamare delete sul IHttpStoredContext puntatore quando non è più necessario. Se è necessaria la pulizia, è possibile chiamare il metodo IHttpStoredContext::CleanupStoredContext .
Note per i chiamanti
IHttpModuleContextContainer gli implementatori sono responsabili della gestione della memoria con questi dati; pertanto, IHttpModuleContextContainer i client non devono rilasciare o chiamare delete sul puntatore restituito IHttpStoredContext quando questi dati non sono più necessari.
Esempio
L'esempio di codice seguente illustra come creare un modulo globale in ascolto di eventi GL_TRACE_EVENT e quindi scrive informazioni IHttpStoredContext personalizzate nel Visualizzatore eventi.
Attenzione
IIS 7 genera un numero elevato di eventi nel Visualizzatore eventi. Per evitare un errore di overflow del log in un ambiente di produzione, è in genere consigliabile evitare di scrivere informazioni sulla cache nel registro eventi. A scopo dimostrativo, questo esempio di codice scrive una voce nella Visualizzatore eventi solo in modalità di debug.
#pragma warning( disable : 4290 )
#pragma warning( disable : 4530 )
#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <tchar.h>
#include <initguid.h>
#include <httptrace.h>
#include <httpserv.h>
#include <httpcach.h>
#include <string>
using namespace std;
// The CConvert class mirrors the Convert class that is
// defined in the .NET Framework. It converts primitives
// and other data types to wstring types.
class CConvert
{
public:
// The ToByteString converts a double-byte
// character string to a single-byte string.
// str: the double-byte string to convert.
// return: a single-byte string copied from str.
static string ToByteString(const wstring& str)
{
// Get the length of the
// double-byte string.
size_t length = str.length();
// Create a temporary char pointer.
char* byteChar = new char[length+1];
byteChar[0] = '\0';
// Copy the double-byte character string
// into the single-byte string.
size_t charsReturned = 0;
wcstombs_s(&charsReturned, byteChar,
length+1, str.c_str(), length+1);
// Create a string to return.
string retString = byteChar;
// Delete the temporary string and
// set that string to NULL.
delete[] byteChar;
byteChar = NULL;
// Return the single-byte string.
return retString;
}
};
// The CEventWriter class writes XML
// documents and strings to the event log.
class CEventWriter
{
public:
// Creates the CEventWriter class.
// name: the name of the
// event log to open.
CEventWriter(const wstring& name)
{
#ifdef UNICODE
m_eventLog = RegisterEventSource(NULL, name.c_str());
#else
string multiName = CConvert::ToByteString(name);
m_eventLog = RegisterEventSource(NULL, multiName.c_str());
#endif
}
// Creates the destructor for the
// CEventWriter class. This destructor
// closes the HANDLE to the event
// log if that HANDLE is open.
virtual ~CEventWriter()
{
// If the HANDLE to the event
// log is open, close it.
if (NULL != m_eventLog)
{
// Deregister the event log HANDLE.
DeregisterEventSource(m_eventLog);
// Set the HANDLE to NULL.
m_eventLog = NULL;
}
}
// The ReportInfo method writes
// a wstring to the event log.
// info: the wstring to write.
// return: true if the event log is written.
BOOL ReportInfo(const wstring& info)
{
return ReportEvent(EVENTLOG_INFORMATION_TYPE, info);
}
protected:
// The ReportEvent method accepts an event type
// and a wstring, and attempts to write that
// event to the event log.
// type: the type of the event.
// data: the wstring to write to the event log.
// return: true if the event log is written;
// otherwise, false.
BOOL ReportEvent(WORD type, const wstring& data)
{
// If the m_eventLog HANDLE
// is NULL, return false.
if (NULL == m_eventLog)
{
return FALSE;
}
#ifndef _DEBUG
// If the current build is not debug,
// return so the event log is not written.
return TRUE;
#endif
#ifdef UNICODE
// The unicode version of the ReportEvent
// method requires double-byte strings.
PCWSTR arr[1];
arr[0] = data.c_str();
return ::ReportEvent(m_eventLog,
type,
0, 0, NULL, 1,
0, arr, (void*)arr);
#else
// The non-unicode version of the ReportEvent
// method requires single-byte strings.
string multiByte =
CConvert::ToByteString(data);
LPCSTR arr[1];
arr[0] = multiByte.c_str();
return ::ReportEvent(m_eventLog,
type,
0, 0, NULL, 1,
0, arr, (void*)arr);
#endif
}
private:
// Specify the HANDLE to the
// event log for writing.
HANDLE m_eventLog;
};
// The CStoredContext class implements
// the IHttpStoredContext interface.
class CStoredContext : public IHttpStoredContext
{
public:
// The constructor for the CStoredContext
// class. Initializes a CEventWriter to write
// to the Event Log.
CStoredContext() : m_eventWriter(L"IISADMIN")
{
// Create a string to write.
wstring constructor(L"CStoredContext::Constructor");
// Write the string to the Event Log.
m_eventWriter.ReportInfo(constructor);
}
// The Display method writes
// L"CStoredContext::Display"
// to the Event Log.
virtual void Display()
{
// Create the string to write.
wstring display(L"CStoredContext::Display");
// Write the string to the Event Log.
m_eventWriter.ReportInfo(display);
}
// The CleanupStoredContext is the pure virtual
// method that all non-abstract classes implementing
// the IHttpStoredContext must implement.
virtual void CleanupStoredContext()
{
wstring cleanup(L"CStoredContext::CleanupStoredContext");
m_eventWriter.ReportInfo(cleanup);
delete this;
}
protected:
// The protected destructor for the
// CStoredContext class. This method is
// protected because the clients of this
// class should dispose of a class instance
// by calling the CleanupStoredContext method.
virtual ~CStoredContext()
{
wstring destructor(L"CStoredContext::Destructor");
m_eventWriter.ReportInfo(destructor);
}
private:
// Specify the private CEventWriter
// for writing events.
CEventWriter m_eventWriter;
};
// The CGlobalTraceModule class creates the CGlobalModule
// class and registers for GL_TRACE_EVENT events.
class CGlobalContainerModule : public CGlobalModule
{
public:
// Creates the destructor for the
// CGlobalTraceModule class.
virtual ~CGlobalContainerModule()
{
}
// The RegisterGlobalModule method creates and registers
// a new CGlobalTraceModule for GL_TRACE_EVENT events.
// dwServerVersion: the current server version.
// pModuleInfo: the current IHttpModuleRegistrationInfo pointer.
// pGlobalInfo: the current IHttpServer pointer.
// return: ERROR_NOT_ENOUGH_MEMORY if the heap is out of
// memory; otherwise, the value from the call to the
// SetGlobalNotifications method on the pModuleInfo pointer.
static HRESULT RegisterGlobalModule
(
DWORD dwServerVersion,
IHttpModuleRegistrationInfo* pModuleInfo,
IHttpServer* pGlobalInfo
)
{
// The IHttpModuleRegistrationInfo
// pointermust not be NULL.
if (NULL == pModuleInfo)
{
return E_INVALIDARG;
}
// Get the HTTP_MODULE_ID from the
// IHttpModuleRegistrationInfo pointer.
HTTP_MODULE_ID moduleId =
pModuleInfo->GetId();
// The HTTP_MODULE_ID pointer
// must not be NULL.
if (NULL == moduleId)
{
return E_INVALIDARG;
}
// Create a new CGlobalContainerModule pointer
// using the HTTP_MODULE_ID from the
// IHttpModuleRegistrationInfo pointer.
CGlobalContainerModule* containerModule =
new CGlobalContainerModule(moduleId);
// Return an out-of-memory error if the containerModule
// is NULL after the call to the new operator.
if (NULL == containerModule)
{
return HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY);
}
// Attempt to set global notification
// for an GL_TRACE_EVENT event by using
// the traceModule as a listener.
HRESULT hr = pModuleInfo->SetGlobalNotifications
(containerModule, GL_TRACE_EVENT);
// Return the HRESULT from the call to
// the SetGlobalNotifications method.
return hr;
}
// The OnGlobalTraceEvent method is the callback
// method for GL_TRACE_EVENT events in the pipeline.
// pProvider: the IGlobalTraceEventProvider pointer.
// return: GL_NOTIFICATION_CONTINUE.
virtual
GLOBAL_NOTIFICATION_STATUS
OnGlobalTraceEvent
(
IN IGlobalTraceEventProvider* pProvider
)
{
// If the IGlobalTraceEventProvider pointer
// is NULL, return GL_NOTIFICATION_CONTINUE.
if (NULL == pProvider)
{
return GL_NOTIFICATION_CONTINUE;
}
// Declare an IHttpContext pointer.
IHttpContext* httpContext = NULL;
// Declare an HRESULT and initialize
// the HRESULT to E_FAIL.
HRESULT hr = E_FAIL;
// Call the GetCurrentHttpRequestContext
// method on the IGlobalTraceEventProvider
// pointer.
hr = pProvider->GetCurrentHttpRequestContext(&httpContext);
// If the GetCurrentHttpRequestContext
// method failed, or the IHttpContext
// pointer is NULL, return GL_NOTIFICATION_CONTINUE.
if (FAILED(hr) || (NULL == httpContext))
{
return GL_NOTIFICATION_CONTINUE;
}
// Get the IHttpModuleContextContainer
// pointer from the IHttpContext pointer.
IHttpModuleContextContainer* container =
httpContext->GetModuleContextContainer();
// If the IHttpModuleContextContainer is
// NULL, return GL_NOTIFICATION_CONTINUE.
if (NULL == container)
{
return GL_NOTIFICATION_CONTINUE;
}
// Get the IHttpStoredContext pointer
// from the IHttpModuleContextContainer
// pointer.
IHttpStoredContext* storedContext =
container->GetModuleContext(m_moduleId);
// If the IHttpStoredContext pointer is
// non-NULL, use the dynamic_cast operator
// to retrieve the CStoredContext pointer
// from the storedContext.
if (NULL != storedContext)
{
// Attempt to cast the IHttpStoredContext
// pointer to a CStoredContext pointer.
CStoredContext* customContext =
dynamic_cast<CStoredContext*>(storedContext);
// If the cast does not return
// NULL, ask the CStoredContext
// poitner to display itself.
if (NULL != customContext)
{
customContext->Display();
}
}
if (NULL == storedContext)
{
// Create a custom CStoredContext pointer.
IHttpStoredContext* customContext =
new CStoredContext;
// Call the SetModuleContext method using
// the IHttpModuleContextContainer pointer.
container->SetModuleContext(customContext, m_moduleId);
}
// Return GL_NOTIFICATION_CONTINUE.
return GL_NOTIFICATION_CONTINUE;
}
// The Terminate method is required for
// non-abstract CGlobalTraceModule classes.
// This method calls delete on this.
virtual VOID Terminate(VOID)
{
delete this;
}
protected:
// Creates the constructor for the CGlobalTraceModule
// class. This constructor initializes the CEventWriter
// to write to the application event log.
// moduleId: the current module identifier.
CGlobalContainerModule(HTTP_MODULE_ID moduleId)
{
m_moduleId = moduleId;
}
private:
// Specify the HTTP_MODULE_ID
// for this module.
HTTP_MODULE_ID m_moduleId;
};
// The RegisterModule method is the
// main entry point for the DLL.
// dwServerVersion: the current server version.
// pModuleInfo: the current
// IHttpModuleRegistrationInfo pointer.
// pGlobalInfo: the current IHttpServer pointer.
// return: the value returned by calling the
// CGlobalContainerModule::RegisterGlobalModule
// method.
HRESULT
__stdcall
RegisterModule(
DWORD dwServerVersion,
IHttpModuleRegistrationInfo* pModuleInfo,
IHttpServer* pGlobalInfo
)
{
// Call the static method for initialization.
return CGlobalContainerModule::RegisterGlobalModule
(dwServerVersion,
pModuleInfo,
pGlobalInfo);
}
Il codice precedente scrive un nuovo evento nella Visualizzatore eventi, in cui la casella Dati contiene stringhe consecutive simili alle seguenti.
CStoredContext::Destructor
CStoredContext::CleanupStoredContext
CStoredContext::Display
CStoredContext::Constructor
Il modulo deve esportare la funzione RegisterModule . È 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 di chiamata anziché dichiarare in modo esplicito la convenzione di chiamata 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 |