Funzione EnumerateTraceGuidsEx (evntrace.h)
Recupera informazioni sui provider di traccia eventi attualmente in esecuzione nel computer.
Sintassi
ULONG WMIAPI EnumerateTraceGuidsEx(
[in] TRACE_QUERY_INFO_CLASS TraceQueryInfoClass,
[in] PVOID InBuffer,
[in] ULONG InBufferSize,
[out] PVOID OutBuffer,
[in] ULONG OutBufferSize,
[out] PULONG ReturnLength
);
Parametri
[in] TraceQueryInfoClass
Determina il tipo di informazioni da restituire. Per i valori possibili, vedere l'enumerazione TRACE_QUERY_INFO_CLASS .
[in] InBuffer
GUID del provider o del gruppo di provider le cui informazioni si desidera recuperare. Specificare il GUID solo se TraceQueryInfoClass è TraceGuidQueryInfo o TraceGroupQueryInfo.
[in] InBufferSize
Dimensioni, in byte, dei dati InBuffer.
[out] OutBuffer
Buffer allocato dall'applicazione contenente le informazioni enumerate. Il formato delle informazioni dipende dal valore di TraceQueryInfoClass.
[in] OutBufferSize
Dimensioni, in byte, del buffer OutBuffer . Se la funzione ha esito positivo, il parametro ReturnLength riceve le dimensioni del buffer usato. Se il buffer è troppo piccolo, la funzione restituisce ERROR_INSUFFICIENT_BUFFER e il parametro ReturnLength riceve le dimensioni del buffer necessarie. Se la dimensione del buffer è zero nell'input, non vengono restituiti dati nel buffer e il parametro ReturnLength riceve le dimensioni del buffer necessarie.
[out] ReturnLength
Dimensioni effettive dei dati in OutBuffer, in byte.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore di sistema. Di seguito sono riportati alcuni errori comuni e le relative cause.
ERROR_INVALID_PARAMETER
Uno dei parametri non è valido.
ERROR_INSUFFICIENT_BUFFER
Il buffer OutBuffer è troppo piccolo per ricevere informazioni per tutti i provider registrati. Riallocare il buffer usando le dimensioni restituite in ReturnLength.
Commenti
Questa funzione restituisce informazioni sui provider di traccia eventi avviati (tramite RegisterTraceGuids o EventRegister) e non sono ancora stati arrestati.
Nota
Per ottenere informazioni sui manifesti del provider registrati nel sistema (ad esempio manifesti registrati tramite wevtutil), usare TdhEnumerateProviders.
Se TraceQueryInfoClass è TraceGuidQueryInfo, ETW restituisce i dati in un blocco TRACE_GUID_INFO che corrisponde a un'intestazione alle informazioni. Il blocco di informazioni contiene un blocco TRACE_PROVIDER_INSTANCE_INFO per ogni provider che usa lo stesso GUID. Ogni blocco di informazioni dell'istanza contiene una struttura TRACE_ENABLE_INFO per ogni sessione che ha abilitato il provider.
Esempio
Nell'esempio seguente viene illustrato come chiamare questa funzione.
#include <windows.h>
#include <stdio.h>
#include <evntcons.h>
DWORD GetProviderInfo(GUID ProviderGuid, PTRACE_GUID_INFO& pInfo);
int wmain(void)
{
ULONG status = ERROR_SUCCESS;
GUID* pTemp = NULL;
GUID* pGuids = NULL;
DWORD GuidListSize = 0;
DWORD GuidCount = 0;
DWORD RequiredListSize = 0;
WCHAR ProviderGuid[50];
PTRACE_GUID_INFO pInfo = NULL;
PTRACE_PROVIDER_INSTANCE_INFO pInstance = NULL;
PTRACE_ENABLE_INFO pEnable = NULL;
// Get the required buffer size for the query.
status = EnumerateTraceGuidsEx(TraceGuidQueryList, NULL, 0, pGuids, GuidListSize, &RequiredListSize);
// The number of registered providers could change between the
// time you called to get the buffer size and the time you called
// to get the actual data, so call EnumerateTraceGuidsEx in a loop
// until you no longer get ERROR_INSUFFICIENT_BUFFER.
while (ERROR_INSUFFICIENT_BUFFER == status)
{
pTemp = (GUID*)realloc(pGuids, RequiredListSize);
if (NULL == pTemp)
{
printf("Error allocating memory for list of provider GUIDs.\n");
goto cleanup;
}
pGuids = pTemp;
pTemp = NULL;
GuidListSize = RequiredListSize;
ZeroMemory(pGuids, GuidListSize);
status = EnumerateTraceGuidsEx(TraceGuidQueryList, NULL, 0, pGuids, GuidListSize, &RequiredListSize);
}
if (ERROR_SUCCESS == status)
{
GuidCount = GuidListSize / sizeof(GUID);
// For each registered provider on the computer, get information
// about how it was registered. If a session enabled the
// provider, get information on how the session enabled the provider.
for (USHORT i = 0; i < GuidCount; i++)
{
StringFromGUID2(pGuids[i], ProviderGuid, sizeof(ProviderGuid));
printf("Provider: %ls\n", ProviderGuid);
status = GetProviderInfo(pGuids[i], pInfo);
if (ERROR_SUCCESS == status)
{
pInstance = (PTRACE_PROVIDER_INSTANCE_INFO)((PBYTE)pInfo + sizeof(TRACE_GUID_INFO));
if (pInfo->InstanceCount > 1)
{
printf("There are %d providers that use the same GUID.\n", pInfo->InstanceCount);
}
for (DWORD j = 0; j < pInfo->InstanceCount; j++)
{
printf("\tThe PID of the process that registered the provider is %lu.\n", pInstance->Pid);
if ((pInstance->Flags & TRACE_PROVIDER_FLAG_PRE_ENABLE) == TRACE_PROVIDER_FLAG_PRE_ENABLE)
{
printf("\tThe provider is not registered; however, one or more sessions have enabled the provider.\n");
}
else
{
if ((pInstance->Flags & TRACE_PROVIDER_FLAG_LEGACY) == TRACE_PROVIDER_FLAG_LEGACY)
{
printf("\tThe provider used RegisterTraceGuids to register itself.\n");
}
else
{
printf("\tThe provider used EventRegister to register itself.\n");
}
}
if (pInstance->EnableCount > 0)
{
printf("\tThe provider is enabled to the following sessions.\n");
pEnable = (PTRACE_ENABLE_INFO)((PBYTE)pInstance + sizeof(TRACE_PROVIDER_INSTANCE_INFO));
for (DWORD k = 0; k < pInstance->EnableCount; k++)
{
printf("\t\tSession Id: %hu\n", pEnable->LoggerId);
printf("\t\tLevel used to enable the provider: %hu\n", pEnable->Level);
printf("\t\tMatchAnyKeyword value used to enable the provider: %I64u\n", pEnable->MatchAnyKeyword);
printf("\t\tMatchAllKeyword value used to enable the provider: %I64u\n", pEnable->MatchAllKeyword);
if (pEnable->EnableProperty > 0)
{
printf("\t\tThe session requested that the following information be included with each event:\n");
if ((pEnable->EnableProperty & EVENT_ENABLE_PROPERTY_SID) == EVENT_ENABLE_PROPERTY_SID)
{
printf("\t\t\tThe SID of the user that logged the event\n");
}
if ((pEnable->EnableProperty & EVENT_ENABLE_PROPERTY_TS_ID) == EVENT_ENABLE_PROPERTY_TS_ID)
{
printf("\t\t\tThe terminal session ID\n");
}
}
pEnable++;
printf("\n");
}
}
pInstance = (PTRACE_PROVIDER_INSTANCE_INFO)((PBYTE)pInstance + pInstance->NextOffset);
printf("\n");
}
printf("\n");
}
else
{
printf("Error retrieving provider info (%lu)\n\n", status);
}
}
printf("\nRegistered provider count is %lu.\n", GuidCount);
}
else
{
printf("EnumerateTraceGuidsEx(TraceGuidQueryList) failed with %lu.\n", status);
goto cleanup;
}
cleanup:
if (pGuids)
{
free(pGuids);
pGuids = NULL;
}
if (pInfo)
{
free(pInfo);
pInfo = NULL;
}
return 0;
}
// Get information about the specified provider.
DWORD GetProviderInfo(GUID ProviderGuid, PTRACE_GUID_INFO& pInfo)
{
ULONG status = ERROR_SUCCESS;
PTRACE_GUID_INFO pTemp = NULL;
DWORD InfoListSize = 0;
DWORD RequiredListSize = 0;
status = EnumerateTraceGuidsEx(TraceGuidQueryInfo, &ProviderGuid, sizeof(GUID), pInfo, InfoListSize, &RequiredListSize);
while (ERROR_INSUFFICIENT_BUFFER == status)
{
pTemp = (PTRACE_GUID_INFO)realloc(pInfo, RequiredListSize);
if (NULL == pTemp)
{
printf("Error allocating memory for provider info.\n");
goto cleanup;
}
pInfo = pTemp;
pTemp = NULL;
InfoListSize = RequiredListSize;
ZeroMemory(pInfo, InfoListSize);
status = EnumerateTraceGuidsEx(TraceGuidQueryInfo, &ProviderGuid, sizeof(GUID), pInfo, InfoListSize, &RequiredListSize);
}
if (ERROR_SUCCESS != status)
{
printf("EnumerateTraceGuidsEx(TraceGuidQueryInfo) failed with %lu.\n", status);
}
cleanup:
return status;
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2008 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | evntrace.h |
| Libreria | Advapi32.lib |
| DLL | Advapi32.dll |