다음을 통해 공유

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 반환하고 이 매개 변수를 필요한 버퍼 크기로 설정합니다. 입력 시 버퍼 크기가 0이면 버퍼에 데이터가 반환되지 않으며 이 매개 변수는 필요한 버퍼 크기를 받습니다.

반환 값

성공하면 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
라이브러리 Tdh.lib
DLL Tdh.dll

추가 정보

TdhEnumerateProviderFieldInformation