ホーム › System.Diagnostics.Etw › EnumerateTraceGuidsEx

EnumerateTraceGuidsEx

関数

登録済みトレースプロバイダーやセッションの情報を列挙する。

DLLADVAPI32.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// ADVAPI32.dll
#include <windows.h>

WIN32_ERROR EnumerateTraceGuidsEx(
    TRACE_QUERY_INFO_CLASS TraceQueryInfoClass,
    void* InBuffer,   // optional
    DWORD InBufferSize,
    void* OutBuffer,   // optional
    DWORD OutBufferSize,
    DWORD* ReturnLength
);

パラメーター

名前	型	方向	説明
TraceQueryInfoClass	TRACE_QUERY_INFO_CLASS	in	返す情報の種類を決定します。指定可能な値については、 TRACE_QUERY_INFO_CLASS 列挙型を参照してください。
InBuffer	void*	inoptional	情報を取得する対象のプロバイダーまたはプロバイダーグループの GUID です。 GUID は TraceQueryInfoClass が TraceGuidQueryInfo または TraceGroupQueryInfo の場合にのみ指定します。
InBufferSize	DWORD	in	InBuffer のデータのサイズ(バイト単位)です。
OutBuffer	void*	outoptional	列挙された情報を格納する、アプリケーションが割り当てたバッファーです。情報の形式は TraceQueryInfoClass の値によって異なります。
OutBufferSize	DWORD	in	OutBuffer バッファーのサイズ(バイト単位)です。関数が成功した場合、 ReturnLength パラメーターには使用されたバッファーのサイズが格納されます。バッファーが小さすぎる場合、関数は `ERROR_INSUFFICIENT_BUFFER` を返し、ReturnLength パラメーターには必要なバッファーサイズが格納されます。入力時にバッファーサイズが 0 の場合、バッファーにはデータは返されず、ReturnLength パラメーターに必要なバッファーサイズが格納されます。
ReturnLength	DWORD*	out	OutBuffer 内のデータの実際のサイズ(バイト単位)です。

戻り値の型: WIN32_ERROR

公式ドキュメント

現在実行中のイベントトレースプロバイダーに関する情報を取得します

戻り値

関数が成功した場合、戻り値は ERROR_SUCCESS です。

関数が失敗した場合、戻り値はシステムエラーコードのいずれかになります。以下に一般的なエラーとその原因をいくつか示します。

ERROR_INVALID_PARAMETER

いずれかのパラメーターが無効です。
ERROR_INSUFFICIENT_BUFFER

OutBuffer バッファーが小さすぎて、登録されているすべてのプロバイダーの情報を受け取ることができません。ReturnLength で返されたサイズを使用してバッファーを再割り当てしてください。

解説(Remarks)

この関数は、開始済みで( RegisterTraceGuids または EventRegister を介して)、まだ停止されていないイベントトレースプロバイダーに関する情報を返します。

メモ

システムに登録されているプロバイダーマニフェスト(すなわち wevtutil を介して登録されたマニフェスト)に関する情報を取得するには、 TdhEnumerateProviders を使用してください。

TraceQueryInfoClass が TraceGuidQueryInfo の場合、ETW は情報のヘッダーとなる TRACE_GUID_INFO ブロックでデータを返します。この情報ブロックには、同じ GUID を使用する各プロバイダーに対応する TRACE_PROVIDER_INSTANCE_INFO ブロックが含まれます。各インスタンス情報ブロックには、プロバイダーを有効化した各セッションに対応する TRACE_ENABLE_INFO 構造体が含まれます。

Examples

次の例は、この関数を呼び出す方法を示しています。

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

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// ADVAPI32.dll
#include <windows.h>

WIN32_ERROR EnumerateTraceGuidsEx(
    TRACE_QUERY_INFO_CLASS TraceQueryInfoClass,
    void* InBuffer,   // optional
    DWORD InBufferSize,
    void* OutBuffer,   // optional
    DWORD OutBufferSize,
    DWORD* ReturnLength
);

[DllImport("ADVAPI32.dll", ExactSpelling = true)]
static extern uint EnumerateTraceGuidsEx(
    int TraceQueryInfoClass,   // TRACE_QUERY_INFO_CLASS
    IntPtr InBuffer,   // void* optional
    uint InBufferSize,   // DWORD
    IntPtr OutBuffer,   // void* optional, out
    uint OutBufferSize,   // DWORD
    out uint ReturnLength   // DWORD* out
);

<DllImport("ADVAPI32.dll", ExactSpelling:=True)>
Public Shared Function EnumerateTraceGuidsEx(
    TraceQueryInfoClass As Integer,   ' TRACE_QUERY_INFO_CLASS
    InBuffer As IntPtr,   ' void* optional
    InBufferSize As UInteger,   ' DWORD
    OutBuffer As IntPtr,   ' void* optional, out
    OutBufferSize As UInteger,   ' DWORD
    <Out> ByRef ReturnLength As UInteger   ' DWORD* out
) As UInteger
End Function

' TraceQueryInfoClass : TRACE_QUERY_INFO_CLASS
' InBuffer : void* optional
' InBufferSize : DWORD
' OutBuffer : void* optional, out
' OutBufferSize : DWORD
' ReturnLength : DWORD* out
Declare PtrSafe Function EnumerateTraceGuidsEx Lib "advapi32" ( _
    ByVal TraceQueryInfoClass As Long, _
    ByVal InBuffer As LongPtr, _
    ByVal InBufferSize As Long, _
    ByVal OutBuffer As LongPtr, _
    ByVal OutBufferSize As Long, _
    ByRef ReturnLength As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

EnumerateTraceGuidsEx = ctypes.windll.advapi32.EnumerateTraceGuidsEx
EnumerateTraceGuidsEx.restype = wintypes.DWORD
EnumerateTraceGuidsEx.argtypes = [
    ctypes.c_int,  # TraceQueryInfoClass : TRACE_QUERY_INFO_CLASS
    ctypes.POINTER(None),  # InBuffer : void* optional
    wintypes.DWORD,  # InBufferSize : DWORD
    ctypes.POINTER(None),  # OutBuffer : void* optional, out
    wintypes.DWORD,  # OutBufferSize : DWORD
    ctypes.POINTER(wintypes.DWORD),  # ReturnLength : DWORD* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ADVAPI32.dll')
EnumerateTraceGuidsEx = Fiddle::Function.new(
  lib['EnumerateTraceGuidsEx'],
  [
    Fiddle::TYPE_INT,  # TraceQueryInfoClass : TRACE_QUERY_INFO_CLASS
    Fiddle::TYPE_VOIDP,  # InBuffer : void* optional
    -Fiddle::TYPE_INT,  # InBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # OutBuffer : void* optional, out
    -Fiddle::TYPE_INT,  # OutBufferSize : DWORD
    Fiddle::TYPE_VOIDP,  # ReturnLength : DWORD* out
  ],
  -Fiddle::TYPE_INT)

#[link(name = "advapi32")]
extern "system" {
    fn EnumerateTraceGuidsEx(
        TraceQueryInfoClass: i32,  // TRACE_QUERY_INFO_CLASS
        InBuffer: *mut (),  // void* optional
        InBufferSize: u32,  // DWORD
        OutBuffer: *mut (),  // void* optional, out
        OutBufferSize: u32,  // DWORD
        ReturnLength: *mut u32  // DWORD* out
    ) -> u32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ADVAPI32.dll")]
public static extern uint EnumerateTraceGuidsEx(int TraceQueryInfoClass, IntPtr InBuffer, uint InBufferSize, IntPtr OutBuffer, uint OutBufferSize, out uint ReturnLength);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ADVAPI32_EnumerateTraceGuidsEx' -Namespace Win32 -PassThru
# $api::EnumerateTraceGuidsEx(TraceQueryInfoClass, InBuffer, InBufferSize, OutBuffer, OutBufferSize, ReturnLength)

#uselib "ADVAPI32.dll"
#func global EnumerateTraceGuidsEx "EnumerateTraceGuidsEx" sptr, sptr, sptr, sptr, sptr, sptr
; EnumerateTraceGuidsEx TraceQueryInfoClass, InBuffer, InBufferSize, OutBuffer, OutBufferSize, varptr(ReturnLength)   ; 戻り値は stat
; TraceQueryInfoClass : TRACE_QUERY_INFO_CLASS -> "sptr"
; InBuffer : void* optional -> "sptr"
; InBufferSize : DWORD -> "sptr"
; OutBuffer : void* optional, out -> "sptr"
; OutBufferSize : DWORD -> "sptr"
; ReturnLength : DWORD* out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ADVAPI32.dll"
#cfunc global EnumerateTraceGuidsEx "EnumerateTraceGuidsEx" int, sptr, int, sptr, int, var
; res = EnumerateTraceGuidsEx(TraceQueryInfoClass, InBuffer, InBufferSize, OutBuffer, OutBufferSize, ReturnLength)
; TraceQueryInfoClass : TRACE_QUERY_INFO_CLASS -> "int"
; InBuffer : void* optional -> "sptr"
; InBufferSize : DWORD -> "int"
; OutBuffer : void* optional, out -> "sptr"
; OutBufferSize : DWORD -> "int"
; ReturnLength : DWORD* out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ADVAPI32.dll"
#cfunc global EnumerateTraceGuidsEx "EnumerateTraceGuidsEx" int, sptr, int, sptr, int, sptr
; res = EnumerateTraceGuidsEx(TraceQueryInfoClass, InBuffer, InBufferSize, OutBuffer, OutBufferSize, varptr(ReturnLength))
; TraceQueryInfoClass : TRACE_QUERY_INFO_CLASS -> "int"
; InBuffer : void* optional -> "sptr"
; InBufferSize : DWORD -> "int"
; OutBuffer : void* optional, out -> "sptr"
; OutBufferSize : DWORD -> "int"
; ReturnLength : DWORD* out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。