Skip to content

Latest commit

 

History

History
140 lines (111 loc) · 4.04 KB

nf-umdprovider-umdetwregister.md

File metadata and controls

140 lines (111 loc) · 4.04 KB
Raw
UID title description old-location tech.root ms.date keywords ms.keywords req.header req.include-header req.target-type req.target-min-winverclnt req.target-min-winversvr req.kmdf-ver req.umdf-ver req.ddi-compliance req.unicode-ansi req.idl req.max-support req.namespace req.assembly req.type-library req.lib req.dll req.irql targetos req.typenames f1_keywords topic_type api_type api_location api_name
NF:umdprovider.UMDEtwRegister
UMDEtwRegister function (umdprovider.h)
Registers the event trace provider. The driver should call this function before it makes any calls to log events.
display\umdetwregister.htm
display
05/10/2018
UMDEtwRegister function
UMDEtwRegister, UMDEtwRegister function [Display Devices], display.umdetwregister, umdprovider/UMDEtwRegister
umdprovider.h
Umdprovider.h
Desktop
Windows 8
Windows Server 2012
Windows
UMDEtwRegister
umdprovider/UMDEtwRegister
APIRef
kbSyntax
DllExport
umdprovider.h
UMDEtwRegister

UMDEtwRegister function

-description

Registers the event trace provider. The driver should call this function before it makes any calls to log events.

-parameters

-param CbRundown

A pointer to a callback function that returns information about the current state of the user-mode driver.

This callback function should call the UMDEtwLogMapAllocation function for every current allocation mapping.

-remarks

The data type for the CbRundown parameter is defined as:

typedef void (*PFNUMDETW_RUNDOWN)();

UMDEtwRegister is defined inline in Umdprovider.h as:

// GUID for UMD ETW provider
// {A688EE40-D8D9-4736-B6F9-6B74935BA3B1}
static const GUID UMDEtwProviderId = 
{ 0xa688ee40, 0xd8d9, 0x4736, { 0xb6, 0xf9, 0x6b, 0x74, 0x93, 0x5b, 0xa3, 0xb1 } };

// Registration handle, returned by EventRegister and passed to EventUnregister
__declspec(selectany) REGHANDLE RegHandle = NULL;

// Whether any level of logging is enabled.
__declspec(selectany) BOOLEAN Enabled = FALSE;

// Whether we are currently in a rundown
__declspec(selectany) BOOLEAN InRundown = FALSE;

// Callback to the driver when a rundown is needed
__declspec(selectany) PFNUMDETW_RUNDOWN Rundown = NULL;

FORCEINLINE void NTAPI EnableCallback(
  __in      LPCGUID SourceId,
  __in      ULONG IsEnabled,
  __in      UCHAR Level,
  __in      ULONGLONG MatchAnyKeyword,
  __in      ULONGLONG MatchAllKeywords,
  __in_opt  PEVENT_FILTER_DESCRIPTOR FilterData,
  __in_opt  PVOID CallbackContext
)
{
    switch (IsEnabled)
    {
        case EVENT_CONTROL_CODE_DISABLE_PROVIDER:
            Enabled = FALSE;
            break;
        case EVENT_CONTROL_CODE_ENABLE_PROVIDER:
            Enabled = TRUE;
            break;
        case EVENT_CONTROL_CODE_CAPTURE_STATE:
            // Temporarily enable logging during the rundown
            BOOLEAN OldEnabled = Enabled;
            Enabled = TRUE;
            
            InRundown = TRUE;
            Rundown();
            InRundown = FALSE;

            // Restore Enabled to its original state
            Enabled = OldEnabled;
            
            break;
    }
}

FORCEINLINE void UMDEtwRegister(PFNUMDETW_RUNDOWN RundownCb)
{
    Rundown = RundownCb;

    // Register the provider
    EventRegister(&UMDEtwProviderId,
                  EnableCallback,
                  NULL,
                  &RegHandle);
}

The EventRegister function and the EVENT_CONTROL_CODE_XXX values are described in the Windows Events documentation.

-see-also

UMDEtwLogMapAllocation

UMDEtwUnregister