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。 否則，除了其他傳回碼之外，此函式還會傳回下列其中一個傳回碼。
| 傳回碼 | 描述 |
|---|---|
|
找不到提供者的中繼資料。 |
|
一或多個參數無效。 |
|
產生的承載篩選準則不符合承載中 EVENT_FILTER_DESCRIPTOR 結構上 EnableTraceEx2 函式所加加的 MAX_EVENT_FILTER_PAYLOAD_SIZE 限制。 |
|
無法配置記憶體以建立承載篩選器。 |
|
找不到所提供提供者 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 |