TdhCreatePayloadFilter 함수(tdh.h)

아티클
08/26/2023

TdhCreatePayloadFilter 함수는 EnableTraceEx2 함수와 함께 사용할 단일 페이로드에 대한 단일 필터를 만듭니다.

구문

TDHSTATUS TdhCreatePayloadFilter(
  [in]  LPCGUID                   ProviderGuid,
  [in]  PCEVENT_DESCRIPTOR        EventDescriptor,
  [in]  BOOLEAN                   EventMatchANY,
  [in]  ULONG                     PayloadPredicateCount,
  [in]  PPAYLOAD_FILTER_PREDICATE PayloadPredicates,
  [out] PVOID                     *PayloadFilter
);

매개 변수

[in] ProviderGuid

EventDescriptor 매개 변수의 매니페스트 공급자를 식별하는 GUID입니다.

[in] EventDescriptor

페이로드가 필터링되는 이벤트 설명자에 대한 포인터입니다.

[in] EventMatchANY

여러 조건을 지정할 때 이벤트가 처리되는 방식을 나타내는 부울 값입니다.

이 매개 변수가 TRUE이면 필터에 지정된 지정된 조건이 TRUE인 경우 이벤트가 세션에 기록됩니다.

이 매개 변수가 FALSE이면 필터에 지정된 모든 조건이 TRUE인 경우에만 이벤트가 세션에 기록됩니다.

[in] PayloadPredicateCount

필터에 지정된 조건 수입니다. 이 값은 Tdh.h 헤더 파일에 정의된 ETW_MAX_PAYLOAD_PREDICATES 상수보다 작거나 같아야 합니다.

[in] PayloadPredicates

필터가 지정하는 목록 조건을 포함하는 PAYLOAD_FILTER_PREDICATE 구조체 배열에 대한 포인터입니다.

[out] PayloadFilter

성공하면 이 매개 변수는 지정된 조건에 맞게 올바르게 크기가 조정되고 빌드된 단일 페이로드 필터에 대한 포인터를 반환합니다.

호출자가 EnableTraceEx2 함수와 함께 반환된 페이로드 필터를 사용하여 완료되면 TdhDeletePayloadFilter 함수를 호출하여 할당된 메모리를 해제해야 합니다.

반환 값

성공하면 ERROR_SUCCESS 반환합니다. 그렇지 않으면 이 함수는 다른 코드 외에도 다음 반환 코드 중 하나를 반환합니다.

반환 코드	설명
ERROR_FILE_NOT_FOUND	공급자에 대한 메타데이터를 찾을 수 없습니다.
ERROR_INVALID_PARAMETER	하나 이상의 매개 변수가 잘못되었습니다.
ERROR_INSUFFICIENT_BUFFER	결과 페이로드 필터는 페이로드의 EVENT_FILTER_DESCRIPTOR 구조에서 EnableTraceEx2 함수에 의해 부과된 MAX_EVENT_FILTER_PAYLOAD_SIZE 제한에 맞지 않습니다.
ERROR_NOT_ENOUGH_MEMORY	페이로드 필터를 만들기 위해 메모리를 할당할 수 없습니다.
ERROR_NOT_FOUND	제공된 공급자 GUID에 대한 스키마 정보를 찾을 수 없습니다.

설명

Windows 8.1 Windows Server 2012 R2 이상에서는 EnableTraceEx2 함수에서 이벤트 페이로드 필터를 사용하여 로거 세션에서 이벤트의 특정 콘텐츠를 필터링할 수 있습니다.

TdhCreatePayloadFilter 함수는 EnableTraceEx2 함수와 함께 사용할 단일 페이로드에 대한 단일 페이로드 필터를 만드는 데 사용됩니다. TdhCreatePayloadFilter는 단일 페이로드 필터에 대해 불투명 데이터 구조를 할당하고 채웁니다. 페이로드 필터가 더 이상 필요하지 않으면 TdhDeletePayloadFilter 함수를 사용하여 페이로드 필터에 할당된 메모리를 해제합니다.

단일 공급자의 경우 여러 이벤트에 고유한 페이로드 필터가 있을 수 있습니다. 동일한 이벤트에 대한 필터가 여러 개 있을 수도 있으며, 이벤트의 필터 중 어느 또는 전부가 통과하는 경우 페이로드가 세션에 전달됩니다.

EnableTraceEx2 함수는 EnableParameters 매개 변수에 전달된 ENABLE_TRACE_PARAMETERS 구조체의 EVENT_FILTER_DESCRIPTOR 구조체 배열을 사용합니다. 배열에는 각 이벤트 필터 형식에 대해 하나의 항목만 있을 수 있습니다. TdhAggregatePayloadFilters 함수를 사용하여 TdhCreatePayloadFilter를 사용하여 만든 단일 공급자에 대한 페이로드 필터 목록을 단일 데이터 구조로 집계하고 EnableTraceEx2 함수에 사용할 EVENT_FILTER_DESCRIPTOR 반환할 수 있습니다.

예제

TdhCreatePayloadFilter 함수를 사용하여 로거 세션의 특정 조건에 대한 필터링에 사용할 페이로드 필터를 만드는 예제는 EnableTraceEx2 함수의 예제를 참조하세요.

요구 사항


지원되는 최소 클라이언트	Windows 8.1 [데스크톱 앱만 해당]
지원되는 최소 서버	Windows Server 2012 R2 [데스크톱 앱만 해당]
대상 플랫폼	Windows
헤더	tdh.h
라이브러리	Tdh.lib
DLL	Tdh.dll