TdhCreatePayloadFilter 函式 (tdh.h)

發行項
03/08/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

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