Consultando eventos
Você pode consultar eventos de um canal ou de um arquivo de log. O canal ou arquivo de log pode existir no computador local ou em um computador remoto. Para especificar os eventos que você deseja obter do canal ou do arquivo de log, use uma consulta XPath ou uma consulta XML de estrutura. Para obter detalhes sobre como gravar a consulta, consulte Consumindo eventos.
Para consultar eventos, chame a função EvtQuery . Você pode especificar a ordem na qual os eventos são retornados (mais antigos para os mais recentes (o padrão) ou o mais novo para o mais antigo) e se deseja tolerar expressões XPath malformadas na consulta (para obter detalhes sobre como a função ignora as expressões malformadas, consulte o sinalizador EvtQueryTolerateQueryErrors ).
O exemplo a seguir mostra como consultar eventos de um canal usando uma expressão XPath.
#include <windows.h>
#include <sddl.h>
#include <stdio.h>
#include <winevt.h>
#pragma comment(lib, "wevtapi.lib")
#define ARRAY_SIZE 10
#define TIMEOUT 1000 // 1 second; Set and use in place of INFINITE in EvtNext call
DWORD PrintResults(EVT_HANDLE hResults);
DWORD PrintEvent(EVT_HANDLE hEvent); // Shown in the Rendering Events topic
void main(void)
{
DWORD status = ERROR_SUCCESS;
EVT_HANDLE hResults = NULL;
LPWSTR pwsPath = L"<Name of the channel goes here>";
LPWSTR pwsQuery = L"Event/System[EventID=4]";
hResults = EvtQuery(NULL, pwsPath, pwsQuery, EvtQueryChannelPath | EvtQueryReverseDirection);
if (NULL == hResults)
{
status = GetLastError();
if (ERROR_EVT_CHANNEL_NOT_FOUND == status)
wprintf(L"The channel was not found.\n");
else if (ERROR_EVT_INVALID_QUERY == status)
// You can call the EvtGetExtendedStatus function to try to get
// additional information as to what is wrong with the query.
wprintf(L"The query is not valid.\n");
else
wprintf(L"EvtQuery failed with %lu.\n", status);
goto cleanup;
}
PrintResults(hResults);
cleanup:
if (hResults)
EvtClose(hResults);
}
O exemplo a seguir mostra como consultar eventos de um canal usando uma consulta XML estruturada. Os eventos são retornados em ordem do mais novo para o mais antigo.
#include <windows.h>
#include <sddl.h>
#include <stdio.h>
#include <winevt.h>
#pragma comment(lib, "wevtapi.lib")
#define ARRAY_SIZE 10
#define TIMEOUT 1000 // 1 second; Set and use in place of INFINITE in EvtNext call
// The structured XML query.
#define QUERY \
L"<QueryList>" \
L" <Query Path='Name of the channel goes here'>" \
L" <Select>Event/System[EventID=4]</Select>" \
L" </Query>" \
L"</QueryList>"
DWORD PrintQueryStatuses(EVT_HANDLE hResults);
DWORD GetQueryStatusProperty(EVT_QUERY_PROPERTY_ID Id, EVT_HANDLE hResults, PEVT_VARIANT& pProperty);
DWORD PrintResults(EVT_HANDLE hResults);
DWORD PrintEvent(EVT_HANDLE hEvent); // Shown in the Rendering Events topic
void main(void)
{
DWORD status = ERROR_SUCCESS;
EVT_HANDLE hResults = NULL;
hResults = EvtQuery(NULL, NULL, QUERY, EvtQueryChannelPath | EvtQueryTolerateQueryErrors);
if (NULL == hResults)
{
// Handle error.
goto cleanup;
}
// Print the status of each query. If all the queries succeeded,
// print the events in the result set. The status can be
// ERROR_EVT_CHANNEL_NOT_FOUND or ERROR_EVT_INVALID_QUERY among others.
if (ERROR_SUCCESS == PrintQueryStatuses(hResults))
PrintResults(hResults);
cleanup:
if (hResults)
EvtClose(hResults);
}
Se você estiver usando uma consulta XML estruturada e passar o sinalizador EvtQueryTolerateQueryErrors para EvtQuery, a função terá êxito mesmo que uma ou mais das consultas na consulta estruturada possam ter realmente falhado. Para determinar quais consultas na consulta estruturada foram bem-sucedidas ou falharam, chame a função EvtGetQueryInfo . Se você não passar o sinalizador EvtQueryTolerateQueryErrors, a função EvtQuery falhará com o primeiro erro encontrado na consulta. Se a consulta falhar com ERROR_EVT_INVALID_QUERY, chame a função EvtGetExtendedStatus para obter uma cadeia de caracteres de mensagem que descreve o erro XPath.
O exemplo a seguir mostra como determinar o sucesso ou a falha de cada consulta em uma consulta estruturada ao passar o sinalizador EvtQueryTolerateQueryErrors para EvtQuery.
// Get the list of paths in the query and the status for each path. Return
// the sum of the statuses, so the caller can decide whether to enumerate
// the results.
DWORD PrintQueryStatuses(EVT_HANDLE hResults)
{
DWORD status = ERROR_SUCCESS;
PEVT_VARIANT pPaths = NULL;
PEVT_VARIANT pStatuses = NULL;
wprintf(L"List of channels/logs that were queried and their status\n\n");
if (status = GetQueryStatusProperty(EvtQueryNames, hResults, pPaths))
goto cleanup;
if (status = GetQueryStatusProperty(EvtQueryStatuses, hResults, pStatuses))
goto cleanup;
for (DWORD i = 0; i < pPaths->Count; i++)
{
wprintf(L"%s (%lu)\n", pPaths->StringArr[i], pStatuses->UInt32Arr[i]);
status += pStatuses->UInt32Arr[i];
}
cleanup:
if (pPaths)
free(pPaths);
if (pStatuses)
free(pStatuses);
return status;
}
// Get the list of paths specified in the query or the list of status values
// for each path.
DWORD GetQueryStatusProperty(EVT_QUERY_PROPERTY_ID Id, EVT_HANDLE hResults, PEVT_VARIANT& pProperty)
{
DWORD status = ERROR_SUCCESS;
DWORD dwBufferSize = 0;
DWORD dwBufferUsed = 0;
if (!EvtGetQueryInfo(hResults, Id, dwBufferSize, pProperty, &dwBufferUsed))
{
status = GetLastError();
if (ERROR_INSUFFICIENT_BUFFER == status)
{
dwBufferSize = dwBufferUsed;
pProperty = (PEVT_VARIANT)malloc(dwBufferSize);
if (pProperty)
{
EvtGetQueryInfo(hResults, Id, dwBufferSize, pProperty, &dwBufferUsed);
}
else
{
wprintf(L"realloc failed\n");
status = ERROR_OUTOFMEMORY;
goto cleanup;
}
}
if (ERROR_SUCCESS != (status = GetLastError()))
{
wprintf(L"EvtGetQueryInfo failed with %d\n", GetLastError());
goto cleanup;
}
}
cleanup:
return status;
}
Lendo eventos do conjunto de resultados
Para enumerar os eventos no conjunto de resultados, chame a função EvtNext em um loop até que a função retorne FALSE e a função GetLastError retorne ERROR_NO_MORE_ITEMS. Os eventos no conjunto de resultados não são estáticos; novos eventos gravados no canal serão incluídos no conjunto de resultados até que ERROR_NO_MORE_ITEMS seja definido. Para melhorar o desempenho, busque eventos do conjunto de resultados em lotes (levando em conta o tamanho de cada evento ao determinar o número de eventos a serem buscados).
O exemplo a seguir mostra como enumerar os eventos em um conjunto de resultados.
// Enumerate all the events in the result set.
DWORD PrintResults(EVT_HANDLE hResults)
{
DWORD status = ERROR_SUCCESS;
EVT_HANDLE hEvents[ARRAY_SIZE];
DWORD dwReturned = 0;
while (true)
{
// Get a block of events from the result set.
if (!EvtNext(hResults, ARRAY_SIZE, hEvents, INFINITE, 0, &dwReturned))
{
if (ERROR_NO_MORE_ITEMS != (status = GetLastError()))
{
wprintf(L"EvtNext failed with %lu\n", status);
}
goto cleanup;
}
// For each event, call the PrintEvent function which renders the
// event for display. PrintEvent is shown in RenderingEvents.
for (DWORD i = 0; i < dwReturned; i++)
{
if (ERROR_SUCCESS == (status = PrintEvent(hEvents[i])))
{
EvtClose(hEvents[i]);
hEvents[i] = NULL;
}
else
{
goto cleanup;
}
}
}
cleanup:
for (DWORD i = 0; i < dwReturned; i++)
{
if (NULL != hEvents[i])
EvtClose(hEvents[i]);
}
return status;
}
Para obter detalhes sobre como renderizar os eventos que você obtém do conjunto de resultados, consulte Renderizando eventos.
Se você quiser consultar eventos de onde parou, crie um indicador do último evento que você ler e usá-lo na próxima vez que executar sua consulta. Para obter detalhes, consulte Eventos de indicadores.
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de