TdhQueryProviderFieldInformation 函数 (tdh.h)

从与给定值匹配的字段值的事件说明中检索指定字段的信息。

语法

TDHSTATUS TdhQueryProviderFieldInformation(
  [in]      LPGUID                    pGuid,
  [in]      ULONGLONG                 EventFieldValue,
  [in]      EVENT_FIELD_TYPE          EventFieldType,
  [out]     PPROVIDER_FIELD_INFOARRAY pBuffer,
  [in, out] ULONG                     *pBufferSize
);

参数

[in] pGuid

标识要检索其信息的提供程序的 GUID。

[in] EventFieldValue

如果字段的值与此值匹配，则检索有关字段的信息。 如果字段类型为关键字 (keyword) ，则为掩码中包含的每个事件检索关键字 (keyword) 位的信息。

[in] EventFieldType

指定要检索其信息的字段的类型。 有关可能的值，请参阅 EVENT_FIELD_TYPE 枚举。

[out] pBuffer

用户分配的用于接收字段信息的缓冲区。 有关详细信息，请参阅 PROVIDER_FIELD_INFOARRAY 结构。

[in, out] pBufferSize

pBuffer 缓冲区的大小（以字节为单位）。 如果函数成功，此参数将接收所用缓冲区的大小。 如果缓冲区太小，该函数将返回ERROR_INSUFFICIENT_BUFFER并将此参数设置为所需的缓冲区大小。 如果输入时缓冲区大小为零，则缓冲区中不返回任何数据，并且此参数接收所需的缓冲区大小。

返回值

如果成功，则返回ERROR_SUCCESS。 否则，除了其他返回代码之外，此函数还返回以下返回代码之一。

返回代码	说明
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 QueryFieldInfo(LPGUID pProvider, EVENT_FIELD_TYPE fieldType, ULONGLONG fieldValue);

// 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 channel information if the provider defines a channel
    // whose value is 17. Returns one entry if the channel exists.

    wprintf(L"Retrieve EventChannelInformation for channel value 17.\n");

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

    // Retrieve keyword information for keywords whose value is 2 or 8.

    wprintf(L"Retrieve EventKeywordInformation for keywords 2 and 8.\n");

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

// Prints the information associated with the specified field type.
DWORD QueryFieldInfo(LPGUID pProvider, EVENT_FIELD_TYPE fieldType, ULONGLONG fieldValue)
{
    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 = TdhQueryProviderFieldInformation(pProvider, fieldValue, 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 and value.

        status = TdhQueryProviderFieldInformation(pProvider, fieldValue, 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"TdhQueryProviderFieldInformation failed with %lu.\n", status);
        }

        goto cleanup;
    }

cleanup:

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

    return status;
}

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	tdh.h
Library	Tdh.lib
DLL	Tdh.dll

另请参阅

TdhEnumerateProviderFieldInformation