TdhCreatePayloadFilter 函式 (tdh.h)

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

GUID,識別 EventDescriptor 參數的資訊清單提供者。

[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

另請參閱

ENABLE_TRACE_PARAMETERS

EVENT_DESCRIPTOR

EVENT_FILTER_DESCRIPTOR

EnableTraceEx2

PAYLOAD_FILTER_PREDICATE

TdhAggregatePayloadFilters

TdhCleanupPayloadEventFilterDescriptor

TdhDeletePayloadFilter