EtwEventRegister

This function registers an event provider.

Declaration

ULONG
EVNTAPI
EtwEventRegister (
    LPCGUID ProviderId,
    PENABLECALLBACK EnableCallback,
    PVOID CallbackContext,
    PREGHANDLE RegHandle);

Parameters

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

The EnableCallback argument is the address of a function that is to be called back whenever the provider is enabled or disabled. 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 function. This argument is valid only if a callback function is supplied.

The RegHandle argument is the address of a 64-bit variable that is to receive a handle to the registered provider.

Callback

The callback function has the prototype

typedef VOID (NTAPI *PENABLECALLBACK) (
    LPCGUID SourceId,
    ULONG IsEnabled,
    UCHAR Level,
    ULONGLONG MatchAnyKeyword,
    ULONGLONG MatchAllKeyword,
    PEVENT_FILTER_DESCRIPTOR FilterData,
    PVOID CallbackContext);

Behaviour

It is an error (ERROR_INVALID_PARAMETER) to give a non-NULL callback context but no callback function.

The function is implemented in terms of the undocumented function EtwNotificationRegister. In translating to that function’s form, the EtwEventRegister function requires a small amount of memory from the process heap to support the callback and context. Failure to get this memory is an error (ERROR_NOT_ENOUGH_MEMORY) for the function.

It is permitted that the given provider, as specified by the GUID, is already known. The obvious intention is that an event controller may enable a provider in any number of loggers not just without knowing whether the provider is yet registered but actually in anticipation of catching all of the provider’s output from the moment it registers itself and starts writing events. That said, it is also explicitly supported that the provider is known because of multiple registration.

If the provider is not already registered or enabled, then memory (specifically, non-paged pool) is required for a new structure (an ETW_GUID_ENTRY) to represent the provider and may also be required for a security descriptor. Failure is indicated by returning STATUS_NO_MEMORY. This is also returned if too many providers are already registered or enabled. The limit is 0x8000.

Each registration of a provider is represented by another structure (an ETW_REG_ENTRY) that is created as an EtwRegistration object (again in non-paged pool). This is formally an object in the sense of being subject to the Object Manager. Failure to create this object is fatal to the function. Note that when registering a user-mode provider, the registration handle is formally a handle to this object and cannot be obtained without WMIGUID_NOTIFICATION and TRACELOG_REGISTER_GUIDS permissions.

The provider may already be enabled for as many as eight loggers. Each has its own logger mode. An undocumented mode represented by 0x01000000 is of special concern, since it specifies that the logger may use paged pool. Loggers in this mode are not tolerated, but neither are they fatal. The logger mode can change. Until then, the function leaves the provider both registered and enabled but masks such loggers from being sent events.

If a callback function is supplied and the provider is already enabled, then the callback function is called immediately. The SourceId argument in this case is always for GUID_NULL no matter what SourceId was given by any of the loggers that enabled the provider. The IsEnabled argument is trivially TRUE. The FilterData argument is always NULL. The CallbackContext argument is the same as given to the EtwRegister function. For the other arguments, remember that the different loggers for which the provider is enabled each specify their own settings. The callback function receives an aggregate: the highest Level; the bit-wise OR of the MatchAnyKeyword from each logger; and the bit-wise AND of the MatchAllKeyword.

Whether or not the provider is already enabled for any logger, the callback function will be called each time that the provider subsequently is enabled or disabled for any logger.

Availability

The EtwRegister is exported from the NT kernel in version 6.0 and higher. It is documented in the Windows Driver Kit (WDK) for Windows Vista.