EnumerateTraceGuids function

The EnumerateTraceGuids function retrieves information about registered event trace providers that are running on the computer.

Note  This function has been superseded by EnumerateTraceGuidsEx.
 

Syntax

ULONG WMIAPI EnumerateTraceGuids(
  PTRACE_GUID_PROPERTIES *GuidPropertiesArray,
  ULONG                  PropertyArrayCount,
  PULONG                 GuidCount
);

Parameters

GuidPropertiesArray

An array of pointers to TRACE_GUID_PROPERTIES structures.

PropertyArrayCount

Number of elements in the GuidPropertiesArray array.

GuidCount

Actual number of event tracing providers registered on the computer.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the system error codes. The following table includes some common errors and their causes.

Return code Description
ERROR_INVALID_PARAMETER
One of the following is true:
  • PropertyArrayCount is zero
  • GuidPropertiesArray is NULL
ERROR_MORE_DATA
The property array is too small to receive information for all registered providers (GuidCount is greater than PropertyArrayCount). The function fills the GUID property array with the number of structures specified in PropertyArrayCount.

Remarks

Event trace controllers call this function.

For information on registering event trace providers, see RegisterTraceGuids.

You can use the TRACE_GUID_PROPERTIES.LoggerId member to determine which session enabled the provider if TRACE_GUID_PROPERTIES.IsEnable is TRUE.

The list will not include kernel providers.

Examples

The following example shows you how to call this function.

#include <windows.h>
#include <stdio.h>
#include <wmistr.h>
#include <evntrace.h>

#define MAX_SESSION_NAME_LEN 1024
#define MAX_LOGFILE_PATH_LEN 1024

BOOL IsPrivateSession(DWORD SessionId);

void wmain(void)
{
    ULONG status = ERROR_SUCCESS;
    PTRACE_GUID_PROPERTIES pProviderProperties = NULL; // Buffer that contains the block of property structures
    PTRACE_GUID_PROPERTIES *pProviders = NULL;         // Array of pointers to property structures in ProviderProperties
    PTRACE_GUID_PROPERTIES *pTemp = NULL;
    ULONG RegisteredProviderCount = 0;                 // Actual number of providers registered on the computer
    ULONG ProviderCount = 0;
    ULONG EnabledProviderCount = 0;
    ULONG BufferSize = 0;
    WCHAR ProviderGuid[50];

    // EnumerateTraceGuids requires a valid pointer. Create a dummy
    // allocation, so that you can get the actual allocation size.

    pProviders = (PTRACE_GUID_PROPERTIES *) malloc(sizeof(PTRACE_GUID_PROPERTIES));

    if (NULL == pProviders)
    {
        wprintf(L"Error allocating memory for dummy pProviders allocation.\n");
        goto cleanup;
    }

    // Pass zero for the array size to get the number of registered providers 
    // for this snapshot. Then allocate memory for the block of structures
    // and the array of pointers.

    status = EnumerateTraceGuids(pProviders, ProviderCount, &RegisteredProviderCount);

    if (ERROR_MORE_DATA == status)
    {
        ProviderCount = RegisteredProviderCount;

        BufferSize = sizeof(TRACE_GUID_PROPERTIES) * RegisteredProviderCount;

        pProviderProperties = (PTRACE_GUID_PROPERTIES) malloc(BufferSize);

        if (NULL == pProviderProperties)
        {
            wprintf(L"Error allocating memory for properties.\n");
            goto cleanup;
        }

        ZeroMemory(pProviderProperties, BufferSize);

        pTemp = (PTRACE_GUID_PROPERTIES *) realloc(pProviders, RegisteredProviderCount * sizeof(PTRACE_GUID_PROPERTIES));

        if (NULL == pTemp)
        {
            wprintf(L"Error allocating memory for pProviders allocation.\n");
            goto cleanup;
        }

        pProviders = pTemp;
        pTemp = NULL;

        for (USHORT i = 0; i < RegisteredProviderCount; i++)
        {
            pProviders[i] = &pProviderProperties[i];
        }

        status = EnumerateTraceGuids(pProviders, ProviderCount, &RegisteredProviderCount);

        if (ERROR_SUCCESS == status || ERROR_MORE_DATA == status)
        {
            for (USHORT i=0; i < RegisteredProviderCount; i++)
            {
                StringFromGUID2(pProviders[i]->Guid, ProviderGuid, sizeof(ProviderGuid)),

                wprintf(L"Provider: %s\nEnabled: %s\n",
                    ProviderGuid,
                    (pProviders[i]->IsEnable) ? L"TRUE" : L"FALSE");

                if (pProviders[i]->IsEnable)
                {
                    EnabledProviderCount++;

                    wprintf(L"Session ID: %ld\nPrivate Session: %s\n"
                        L"Enable level: %ld\nEnable flags: %ld\n",
                        pProviders[i]->LoggerId,
                        (IsPrivateSession(pProviders[i]->LoggerId)) ? L"TRUE" : L"FALSE",
                        pProviders[i]->EnableLevel,
                        pProviders[i]->EnableFlags);
                }
      
                wprintf(L"\n");
            }

            wprintf(L"\nRegistered provider count is %lu; %lu of which are enabled.\n", 
                RegisteredProviderCount, EnabledProviderCount);
        }
        else
        {
            wprintf(L"Error calling EnumerateTraceGuids, %d.\n", status);
            goto cleanup;
        }
    }
    else
    {
        wprintf(L"Error calling EnumerateTraceGuids to get allocation size, %d.\n", status);
        goto cleanup;
    }

cleanup:

    if (pProviders)
    {
        free(pProviders);
    }

    if (pProviderProperties)
    {
        free(pProviderProperties);
    }
}


BOOL IsPrivateSession(DWORD SessionId)
{
    DWORD status = ERROR_SUCCESS;
    BOOL IsPrivate = FALSE;
    PEVENT_TRACE_PROPERTIES pProperties;
    ULONG BufferSize = 0;

    BufferSize = sizeof(EVENT_TRACE_PROPERTIES) +
        (MAX_SESSION_NAME_LEN*sizeof(WCHAR)) +
        (MAX_LOGFILE_PATH_LEN*sizeof(WCHAR));

    pProperties = (PEVENT_TRACE_PROPERTIES) malloc(BufferSize);

    if (pProperties)
    {
        ZeroMemory(pProperties, BufferSize);

        pProperties->Wnode.BufferSize = BufferSize;
        pProperties->LoggerNameOffset = sizeof(EVENT_TRACE_PROPERTIES);
        pProperties->LogFileNameOffset = sizeof(EVENT_TRACE_PROPERTIES) + (MAX_SESSION_NAME_LEN*sizeof(WCHAR));
    }
    else
    {
        wprintf(L"Error allocating memory for properties.\n");
        goto cleanup;
    }

    status = ControlTrace((TRACEHANDLE)SessionId, NULL, pProperties, EVENT_TRACE_CONTROL_QUERY);

    if (ERROR_SUCCESS == status)
    {
        if ((EVENT_TRACE_PRIVATE_LOGGER_MODE & pProperties->LogFileMode)== EVENT_TRACE_PRIVATE_LOGGER_MODE)
        {
            IsPrivate = TRUE;
        }
    }
    else if (ERROR_WMI_INSTANCE_NOT_FOUND == status)
    {
        wprintf(L"The session is no longer running\n");
    }
    else
    {
        wprintf(L"ControlTrace(QUERY) failed with %lu\n", status);
    }

cleanup:

    if (pProperties)
    {
        free(pProperties);
        pProperties = NULL;
    }

    return IsPrivate;
}

Requirements

   
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header evntrace.h
Library Advapi32.lib
DLL Advapi32.dll

See Also

EnumerateTraceGuidsEx

QueryAllTraces

RegisterTraceGuids

TRACE_GUID_PROPERTIES