Consulta de eventos
Puede consultar eventos desde un canal o un archivo de registro. El archivo de canal o registro puede existir en el equipo local o en un equipo remoto. Para especificar los eventos que desea obtener del canal o archivo de registro, use una consulta XPath o una consulta XML de estructura. Para obtener más información sobre cómo escribir la consulta, consulte Consumo de eventos.
Para consultar eventos, llame a la función EvtQuery . Puede especificar el orden en el que se devuelven los eventos (más antiguos a los más recientes (predeterminados) o más antiguos) y si se toleran expresiones XPath con formato incorrecto en la consulta (para obtener más información sobre cómo la función omite las expresiones con formato incorrecto, vea la marca EvtQueryTolerateQueryErrors ).
En el ejemplo siguiente se muestra cómo consultar eventos desde un canal mediante una expresión 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);
}
En el ejemplo siguiente se muestra cómo consultar eventos desde un canal mediante una consulta XML estructurada. Los eventos se devuelven en orden de más reciente a más antiguo.
#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);
}
Si usa una consulta XML estructurada y pasa la marca EvtQueryTolerateQueryErrors a EvtQuery, la función se realiza correctamente aunque una o varias de las consultas de la consulta estructurada hayan fallado realmente. Para determinar qué consultas de la consulta estructurada se realizaron correctamente o no, llame a la función EvtGetQueryInfo . Si no pasa la marca EvtQueryTolerateQueryErrors, la función EvtQuery producirá el primer error que encuentra en la consulta. Si se produce un error en la consulta con ERROR_EVT_INVALID_QUERY, llame a la función EvtGetExtendedStatus para obtener una cadena de mensaje que describa el error XPath.
En el ejemplo siguiente se muestra cómo determinar el éxito o el error de cada consulta en una consulta estructurada al pasar la marca EvtQueryTolerateQueryErrors a 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;
}
Lectura de eventos del conjunto de resultados
Para enumerar los eventos del conjunto de resultados, llame a la función EvtNext en un bucle hasta que la función devuelva FALSE y la función GetLastError devuelva ERROR_NO_MORE_ITEMS. Los eventos del conjunto de resultados no son estáticos; Los nuevos eventos que se escriben en el canal se incluirán en el conjunto de resultados hasta que se establezca ERROR_NO_MORE_ITEMS. Para mejorar el rendimiento, capture eventos del conjunto de resultados en lotes (teniendo en cuenta el tamaño de cada evento al determinar el número de eventos que se van a capturar).
En el ejemplo siguiente se muestra cómo enumerar los eventos de un 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 obtener más información sobre cómo representar los eventos que obtiene del conjunto de resultados, vea Rendering Events.
Si desea consultar los eventos desde donde lo dejó, cree un marcador del último evento que lea y úselo la próxima vez que ejecute la consulta. Para obtener más información, consulte Eventos de marcadores.