EtwRegisterClassicProvider

This function registers a kernel-mode event provider that has the classic interface.

Declaration

NTSTATUS
NTKERNELAPI
EtwRegisterClassicProvider (
    LPCGUID ProviderId, 
    ULONG Type, 
    PETW_CLASSIC_CALLBACK EnableCallback,
    PVOID CallbackContext,
    REGHANDLE *RegHandle);

Parameters

The ProviderGuid argument is the address of a GUID that represents the event provider.

The Type argument

The EnableCallback argument is the address of a routine that is to be called back whenever a tracing session interacts with the provider. This argument can be NULL to mean that the caller does not want to be called back.

The CallbackContext argument is a caller-defined context that is to be passed back to the caller as one of the arguments of the callback routine. This argument is valid only if a callback routine is supplied.

The RegHandle argument is the address of a 64-bit variable that is to receive a registration handle to the provider. The caller may use this as an argument when calling other ETW functions, notably to write events through this provider, and ultimately to call EtwUnregister.

Return Value

The function returns STATUS_SUCCESS if successful, else a negative error code.

Callback

The callback routine has the prototype

VOID
EnableCallback (
    LPCGUID Guid,
    UCHAR ControlCode, 
    PVOID EnableContext, 
    PVOID CallbackContext);

Availability

The EtwRegisterClassicProvider function is exported by name from the kernel, starting with the version 6.0 from Windows Vista SP1.

Documentation Status

The EtwRegisterClassicProvider function is not documented. Declarations and even examples of use have, however, been in the plain sight of kernel-mode programmers all along. For all this function’s life, the function has been at the heart of initialising a driver’s use of Windows Pre-Processor (WPP) Tracing, a diagnostic technology that Microsoft introduced for Windows XP (and back-fitted into the later service packs of Windows 2000) and which is in some ways superior to anything that Microsoft has since tried to replace it with. A WPP tool pre-processes kernel-mode or user-mode source files and generates C-language headers to #include in those source files. Starting with the Windows Driver Kit (WDK) for Windows 7, the generated headers use EtwRegisterClassicProvider, with the side-effect that declarations of both the function and the callback have been published in the WPP configuration files.

Behaviour

TO BE DONE