Fungsi EnumerateTraceGuidsEx (evntrace.h)

Mengambil informasi tentang penyedia pelacakan peristiwa yang saat ini berjalan di komputer.

Sintaks

ULONG WMIAPI EnumerateTraceGuidsEx(
  [in]  TRACE_QUERY_INFO_CLASS TraceQueryInfoClass,
  [in]  PVOID                  InBuffer,
  [in]  ULONG                  InBufferSize,
  [out] PVOID                  OutBuffer,
  [in]  ULONG                  OutBufferSize,
  [out] PULONG                 ReturnLength
);

Parameter

[in] TraceQueryInfoClass

Menentukan jenis informasi yang akan dikembalikan. Untuk nilai yang mungkin, lihat enumerasi TRACE_QUERY_INFO_CLASS .

[in] InBuffer

GUID penyedia atau grup penyedia yang informasinya ingin Anda ambil. Tentukan GUID hanya jika TraceQueryInfoClass adalah TraceGuidQueryInfo atau TraceGroupQueryInfo.

[in] InBufferSize

Ukuran, dalam byte, dari data InBuffer.

[out] OutBuffer

Buffer yang dialokasikan aplikasi yang berisi informasi enumerasi. Format informasi tergantung pada nilai TraceQueryInfoClass.

[in] OutBufferSize

Ukuran, dalam byte, dari buffer OutBuffer . Jika fungsi berhasil, parameter ReturnLength menerima ukuran buffer yang digunakan. Jika buffer terlalu kecil, fungsi mengembalikan ERROR_INSUFFICIENT_BUFFER dan parameter ReturnLength menerima ukuran buffer yang diperlukan. Jika ukuran buffer nol pada input, tidak ada data yang dikembalikan dalam buffer dan parameter ReturnLength menerima ukuran buffer yang diperlukan.

[out] ReturnLength

Ukuran aktual data di OutBuffer, dalam byte.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan adalah ERROR_SUCCESS.

Jika fungsi gagal, nilai yang dikembalikan adalah salah satu kode kesalahan sistem. Berikut ini adalah beberapa kesalahan umum dan penyebabnya.

  • ERROR_INVALID_PARAMETER

    Salah satu parameter tidak valid.

  • ERROR_INSUFFICIENT_BUFFER

    Buffer OutBuffer terlalu kecil untuk menerima informasi untuk semua penyedia terdaftar. Realokasikan buffer menggunakan ukuran yang dikembalikan di ReturnLength.

Keterangan

Fungsi ini mengembalikan informasi tentang penyedia pelacakan peristiwa yang telah dimulai (melalui RegisterTraceGuids atau EventRegister) dan belum dihentikan.

Catatan

Untuk mendapatkan informasi tentang manifes penyedia yang telah terdaftar pada sistem (yaitu manifes yang terdaftar melalui wevtutil), gunakan TdhEnumerateProviders.

Jika TraceQueryInfoClass adalah TraceGuidQueryInfo, ETW mengembalikan data dalam blok TRACE_GUID_INFO yang merupakan header ke informasi. Blok info berisi blok TRACE_PROVIDER_INSTANCE_INFO untuk setiap penyedia yang menggunakan GUID yang sama. Setiap blok info instans berisi struktur TRACE_ENABLE_INFO untuk setiap sesi yang mengaktifkan penyedia.

Contoh

Contoh berikut menunjukkan cara memanggil fungsi ini.

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

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows Vista [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2008 [aplikasi desktop | Aplikasi UWP]
Target Platform Windows
Header evntrace.h
Pustaka Advapi32.lib
DLL Advapi32.dll

Lihat juga

TRACE_QUERY_INFO_CLASS