TRACELOGGING_DEFINE_PROVIDER_STORAGE macro (traceloggingprovider.h)

Article
06/10/2022

Reserves static storage for a TraceLogging provider handle that will be defined by the user. Prefer TRACELOGGING_DEFINE_PROVIDER over this macro.

Syntax

void TRACELOGGING_DEFINE_PROVIDER_STORAGE(
  [in]            storageVariable,
  [in]            providerName,
  [in]            providerId,
  [in, optional]  __VA_ARGS__
);

Parameters

[in] storageVariable

The name to use for the static provider storage variable, e.g. MyStaticProviderStorage.

[in] providerName

A string literal with the name of the TraceLogging provider. This name should be specific to your organization and component so that it does not conflict with providers from other components. This name string will be included within each ETW event generated by the provider, so try to use a relatively short name. For example, you might use a name like "MyCompany.MyComponent" or "MyCompany.MyOrganization.MyComponent".

This must be a string literal. Do not use a variable.

[in] providerId

The ETW Control GUID for the provider, specified as a comma-separated list of 11 integers in parentheses. For example, the GUID {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5} would be expressed as (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5).

While any unique GUID can be used for the provider ID, Microsoft recommends using a GUID generated from the provider name using the ETW name-hashing algorithm. See TRACELOGGING_DEFINE_PROVIDER for information about generating the provider ID.

[in, optional] __VA_ARGS__

Optional parameters for the provider. Most providers do not need to specify any optional parameters.

If you want your provider to be associated with an ETW provider group, add the TraceLoggingOptionGroup macro to specify the provider's group GUID. Otherwise, do not specify any __VA_ARGS__ parameters.

Return value

None

Remarks

In most cases you will use TRACELOGGING_DEFINE_PROVIDER instead of this macro. In certain unusual scenarios, you may need to use this macro to allocate static storage for a TraceLogging provider without also declaring the handle variable. Your code will subsequently declare the handle variable as appropriate.

TRACELOGGING_DEFINE_PROVIDER_STORAGE will declare a static variable with the data needed for a provider. You can then create a handle by taking the address of this variable. An invocation of TRACELOGGING_DEFINE_PROVIDER_STORAGE(storageVar, ...) can be thought of as similar to code like:

static TraceLoggingProviderState storageVar = { ... };

Example usage:

TRACELOGGING_DEFINE_PROVIDER_STORAGE( // defines static storageVar
    storageVar, // Name of the storage variable
    "MyCompany.MyComponent", // Human-readable name for the provider
    // {ce5fa4ea-ab00-5402-8b76-9f76ac858fb5}
    (0xce5fa4ea,0xab00,0x5402,0x8b,0x76,0x9f,0x76,0xac,0x85,0x8f,0xb5));

const TraceLoggingHProvider g_hMyProvider = &storageVar; // Make a handle

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2008 [desktop apps \| UWP apps]
Target Platform	Windows
Header	traceloggingprovider.h