イベントのクエリ

[アーティクル]
06/12/2023

チャネルまたはログファイルからイベントのクエリを実行できます。チャネルまたはログファイルは、ローカルコンピューターまたはリモートコンピューターに存在できます。チャネルまたはログファイルから取得するイベントを指定するには、XPath クエリまたは構造体 XML クエリを使用します。クエリの記述の詳細については、「イベントの使用」を参照してください。

イベントのクエリを実行するには、 EvtQuery 関数を呼び出します。イベントが返される順序 (最も古いものから最新のもの (既定値) または最新から最も古いものまで) と、クエリ内の形式が正しくない XPath 式を許容するかどうかを指定できます (関数が正しくない式を無視する方法の詳細については、 EvtQueryTolerateQueryErrors フラグを参照してください)。

次の例は、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);

}

次の例は、構造化 XML クエリを使用してチャネルからイベントを照会する方法を示しています。イベントは、最新から最も古い順に返されます。

#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);

}

構造化 XML クエリを使用し、EvtQueryTolerateQueryErrors フラグを EvtQuery に渡すと、構造化クエリ内の 1 つ以上のクエリが実際に失敗した可能性がある場合でも、関数は成功します。構造化クエリのどのクエリが成功したか失敗したかを確認するには、 EvtGetQueryInfo 関数を呼び出します。 EvtQueryTolerateQueryErrors フラグを渡さない場合、 EvtQuery 関数はクエリで最初に見つかったエラーで失敗します。クエリがERROR_EVT_INVALID_QUERYで失敗した場合は、 EvtGetExtendedStatus 関数を呼び出して、XPath エラーを説明するメッセージ文字列を取得します。

次の例は、EvtQueryTolerateQueryErrors フラグを 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;
}

結果セットからのイベントの読み取り

結果セット内のイベントを列挙するには、関数が FALSE を返し、GetLastError 関数がERROR_NO_MORE_ITEMSを返すまで、ループで EvtNext 関数を呼び出します。結果セット内のイベントは静的ではありません。チャネルに書き込まれる新しいイベントは、ERROR_NO_MORE_ITEMSが設定されるまで結果セットに含まれます。パフォーマンスを向上させるには、結果セットからイベントをバッチでフェッチします (フェッチするイベントの数を決定する際の各イベントのサイズを考慮します)。

次の例は、結果セット内のイベントを列挙する方法を示しています。

// 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;
}

結果セットから取得するイベントのレンダリングの詳細については、「イベントのレンダリング」を参照してください。

中断した場所からイベントのクエリを実行する場合は、最後に読み取ったイベントのブックマークを作成し、次回クエリを実行するときに使用します。詳細については、「イベントのブックマーク」を参照してください。

次の方法で共有

イベントのクエリ

結果セットからのイベントの読み取り

フィードバック

その他のリソース