http-trace-configuration-structure.md

title	HTTP_TRACE_CONFIGURATION Structure
ms.date	10/07/2016
description	The HTTP_TRACE_CONFIGURATION Structure contains tracing information for use with trace providers and consumers.
ms.assetid	933a2496-8b0a-256c-e75f-b0a461b58d20

HTTP_TRACE_CONFIGURATION Structure

Contains tracing information for use with trace providers and consumers.

Syntax

struct HTTP_TRACE_CONFIGURATION{  
   LPCGUID pProviderGuid;  
   DWORD dwAreas;  
   DWORD dwVerbosity;  
   BOOL fProviderEnabled;  
};  

Members

Member name	Description
pProviderGuid	An LPCGUID that represents the unique identifier for the provider.
dwAreas	A DWORD that contains a bitmask that defines the specific areas to trace. This list of areas is private, but a value of 0xffffe will enable tracing for all areas.
dwVerbosity	A DWORD that maps numerical values to their verbose counterparts (the values 0 through 5 map to General, FatalError, Error, Warning, Info, and Verbose).
fProviderEnabled	true if pProviderGuid is initialized to a valid current value; otherwise, false.

Remarks

You can call the IHttpTraceContext::GetTraceConfiguration method to read or write an HTTP_TRACE_CONFIGURATION pointer as an IN/OUT parameter, or you can call the IHttpTraceContext::SetTraceConfiguration method to read an HTTP_TRACE_CONFIGURATION pointer as an IN parameter only. When a trace consumer calls SetTraceConfiguration, the HTTP_TRACE_CONFIGURATION pointer provides the specific areas to trace to an IHttpTraceContext interface.

Note

This list of areas is private, but a value of 0xffffe will enable tracing for all areas.

The HTTP_TRACE_CONFIGURATION pointer also returns information about tracing from a GetTraceConfiguration call.

Before you call SetTraceConfiguration, verify that the HTTP_TRACE_CONFIGURATION pointer and all of its members are initialized. Before you call GetTraceConfiguration, verify that the pProviderGuid member is initialized to a valid current value; otherwise, the fProviderEnabled member will be set to false, and IHttpTraceContext implementers will immediately return.

See IIS Tracing Constants for defined GUID values that can be assigned to the pProviderGuid member.

Caution

Because implementers are required to set only the fProviderEnabled member during a call to GetTraceConfiguration, you should access the remaining members after the method call only if fProviderEnabled is true; otherwise, these remaining members will be unchanged and invalid.

Note

You should initialize all fields to known values before calling either the SetTraceConfiguration or GetTraceConfiguration methods, because the implementation may change.

Example

The following code example demonstrates how to create a global module that listens for GL_CACHE_OPERATION and GL_CACHE_CLEANUP events and then writes the HTTP_TRACE_CONFIGURATION information to the Event Viewer.

Caution

[!INCLUDEiisver] generates a large number of events in the Event Viewer. To avoid a log overflow error in a production environment, you should generally avoid writing cache information to the event log. For demonstration purposes, this code example writes an entry to the Event Viewer in debug mode only.

[!code-cppStructs#1]

The above code writes a new event to the Event Viewer, where the Data box contains XML similar to the following.

<cacheProvider>  
    <traceContext>  
        <traceConfiguration   
            providerGuid="{00000000-0000-0000-1B00-0080000000FF}"   
            areas="0"   
            verbosity="0"   
            providerEnabled="true"/>  
    </traceContext>  
</cacheProvider>  

For more information on how to create and deploy a native DLL module, see Walkthrough: Creating a Request-Level HTTP Module By Using Native Code.

You can optionally compile the code by using the stdcall (/Gz) calling convention instead of explicitly declaring the calling convention for each function.

Requirements

Type	Description
Client	- IIS 7.0 on [!INCLUDEwinvista] - IIS 7.5 on Windows 7 - IIS 8.0 on Windows 8 - IIS 10.0 on Windows 10
Server	- IIS 7.0 on [!INCLUDEwinsrv2008] - IIS 7.5 on Windows Server 2008 R2 - IIS 8.0 on Windows Server 2012 - IIS 8.5 on Windows Server 2012 R2 - IIS 10.0 on Windows Server 2016
Product	- IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0 - [!INCLUDEiisexp75], [!INCLUDEiisexp80], [!INCLUDEiisexp100]
Header	Httptrace.h

See Also

Web Server Core Structures