TdhEnumerateProviderFieldInformation 函式 (tdh.h)

擷取指定提供者的指定欄位元數據。

語法

TDHSTATUS TdhEnumerateProviderFieldInformation(
  [in]            LPGUID                    pGuid,
  [in]            EVENT_FIELD_TYPE          EventFieldType,
  [out, optional] PPROVIDER_FIELD_INFOARRAY pBuffer,
  [in, out]       ULONG                     *pBufferSize
);

參數

[in] pGuid

GUID，識別您想要擷取其資訊的提供者。

[in] EventFieldType

指定您要擷取資訊的欄位類型。 如需可能的值，請參閱 EVENT_FIELD_TYPE 列舉。

[out, optional] pBuffer

使用者配置緩衝區以接收欄位資訊。 如需詳細資訊，請參閱 PROVIDER_FIELD_INFOARRAY 結構。

[in, out] pBufferSize

pBuffer 緩衝區的大小，以位元組為單位。 如果函式成功，此參數會接收所使用的緩衝區大小。 如果緩衝區太小，函式會傳回ERROR_INSUFFICIENT_BUFFER，並將此參數設定為所需的緩衝區大小。 如果輸入上的緩衝區大小為零，則緩衝區中不會傳回任何數據，而且此參數會收到所需的緩衝區大小。

傳回值

如果成功，則傳回ERROR_SUCCESS。 否則，此函式除了傳回其他傳回碼之外，還會傳回下列其中一個傳回碼。

傳回碼	Description
ERROR_INSUFFICIENT_BUFFER	pBuffer 緩衝區的大小太小。 使用 pBufferSize 中設定的必要緩衝區大小來配置新的緩衝區。
ERROR_NOT_SUPPORTED	要求的欄位類型無效。
ERROR_NOT_FOUND	找不到指令清單或MOF類別，或未包含所要求欄位類型的資訊。
ERROR_INVALID_PARAMETER	一或多個參數無效。
ERROR_FILE_NOT_FOUND	指令清單中的 resourceFileName 屬性包含提供者二進位檔的位置。 當您註冊指令清單時，位置會寫入登錄。 TDH 無法根據已註冊的位置找到二進位檔。

備註

此函式會使用 XML 指令清單或 WMI MOF 類別來擷取資訊。

範例

下列範例示範如何列舉所要求字段指令清單或MOF類別中包含的資訊。

#include <windows.h>
#include <stdio.h>
#include <wmistr.h>
#include <evntrace.h>
#include <tdh.h>

#pragma comment(lib, "tdh.lib")

DWORD EnumFieldInfo(LPGUID pProvider, EVENT_FIELD_TYPE fieldType);

// GUID of the provider whose metadata you want to enumerate.

EXTERN_C __declspec(selectany) const GUID ProviderGuid = {0xd8909c24, 0x5be9, 0x4502, {0x98, 0xca, 0xab, 0x7b, 0xdc, 0x24, 0x89, 0x9d}};

void wmain(void)
{
    DWORD status = ERROR_SUCCESS;

    // Retrieve the keyword information.

    wprintf(L"Retrieve EventKeywordInformation\n");

    status = EnumFieldInfo((LPGUID)&ProviderGuid, EventKeywordInformation);
    if (ERROR_SUCCESS != status)
    {
        wprintf(L"Failed to retrieve EventKeywordInformation (%lu).\n\n", status);
    }
}

// Prints the information associated with the specified field type.
DWORD EnumFieldInfo(LPGUID pProvider, EVENT_FIELD_TYPE fieldType)
{
    DWORD status = ERROR_SUCCESS;
    PROVIDER_FIELD_INFOARRAY* penum = NULL;
    DWORD bufferSize = 0;

    // Retrieve the required buffer size. If the status is ERROR_INSUFFICIENT_BUFFER,
    // use bufferSize to allocate the buffer.

    status = TdhEnumerateProviderFieldInformation(pProvider, fieldType, penum, &bufferSize);
    if (ERROR_INSUFFICIENT_BUFFER == status)
    {
        penum = (PROVIDER_FIELD_INFOARRAY*) malloc(bufferSize);
        if (penum == NULL)
        {
            wprintf(L"Allocation failed (size=%lu).\n", bufferSize);
            status = ERROR_OUTOFMEMORY;
            goto cleanup;
        }

        // Retrieve the information for the field type.

        status = TdhEnumerateProviderFieldInformation(pProvider, fieldType, penum, &bufferSize);
    }

    // The first call can fail with ERROR_NOT_FOUND if none of the provider's event
    // descriptions contain the requested field type information.

    if (ERROR_SUCCESS == status)
    {
        // Loop through the list of field information and print the field's name,
        // description (if it exists), and value. 

        for (DWORD i = 0; i < penum->NumberOfElements; i++)
        {
            wprintf(L"Field name: %s\nDescription: %s\nValue: %I64u\n\n",
                (PWCHAR)((PBYTE)(penum) + penum->FieldInfoArray[i].NameOffset),
                (penum->FieldInfoArray[i].DescriptionOffset) ? 
                    (PWCHAR)((PBYTE)(penum) + penum->FieldInfoArray[i].DescriptionOffset): L"",
                penum->FieldInfoArray[i].Value);
        }
    }
    else
    {
        if (ERROR_NOT_FOUND == status)
        {
            wprintf(L"Requested field type not found.\n");
        }
        else
        {
            wprintf(L"TdhEnumerateProviderFieldInformation failed with %lu.\n", status);
        }

        goto cleanup;
    }

cleanup:

    if (penum)
    {
        free(penum);
        penum = NULL;
    }

    return status;
}

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	tdh.h
程式庫	Tdh.lib
Dll	Tdh.dll

另請參閱

TdhEnumerateProviders

TdhQueryProviderFieldInformation