TdhAggregatePayloadFilters 函式 (tdh.h)

發行項
03/02/2024

TdhAggregatePayloadFilters 函式會將單一提供者的多個承載篩選匯總成單一數據結構，以便與 EnableTraceEx2 函式搭配使用。

語法

TDHSTATUS TdhAggregatePayloadFilters(
                 ULONG                    PayloadFilterCount,
                 PVOID                    *PayloadFilterPtrs,
  [in, optional] PBOOLEAN                 EventMatchALLFlags,
  [out]          PEVENT_FILTER_DESCRIPTOR EventFilterDescriptor
);

參數

PayloadFilterCount

承載篩選的計數。

PayloadFilterPtrs

事件承載單一篩選條件的陣列，每個篩選條件都是由呼叫 TdhCreatePayloadFilter 函式所建立。

[in, optional] EventMatchALLFlags

布爾值的陣列，對應至 PayloadFilterPtrs 參數中傳遞的每個承載篩選，並指出指定多個條件時如何處理事件。此參數只會影響針對相同事件指定多個承載篩選的情況。

當布爾值為 TRUE時，如果篩選中指定的任何條件為 TRUE，事件就會寫入會話。如果在相同事件標識碼或事件版本的一或多個篩選上將此旗標設定為 TRUE ，則只有在滿足事件的所有標幟篩選條件時，才會寫入事件。

當布爾值為 FALSE 時，只有在篩選中指定的所有指定條件都是 TRUE 時，才會將事件寫入會話。如果相同事件標識碼或事件版本的一或多個篩選條件將此旗標設定為 FALSE ，則會在滿足任何非標幟篩選條件時寫入事件。

[out] EventFilterDescriptor

要與 EnableTraceEx2 函式搭配使用的EVENT_FILTER_DESCRIPTOR結構的指標。 EVENT_FILTER_DESCRIPTOR 結構將包含此函式已配置之匯總承載篩選的指標。

當呼叫端使用此 EVENT_FILTER_DESCRIPTOR 結構與 EnableTraceEx2 函式完成時，應該呼叫 TdhCleanupPayloadEventFilterDescriptor 函式以釋放配置的記憶體。

傳回值

如果成功，則傳回ERROR_SUCCESS。否則，除了其他傳回碼之外，此函式還會傳回下列其中一個傳回碼。

傳回碼	Description
ERROR_INVALID_PARAMETER	一或多個參數無效。
ERROR_NOT_ENOUGH_MEMORY	無法配置記憶體以建立匯總的承載篩選器。

備註

在 Windows 8.1、Windows Server 2012 R2 及更新版本上，EnableTraceEx2 函式可以使用事件承載篩選，以篩選記錄器會話中的事件特定內容。

TdhAggregatePayloadFilters 函式會將單一提供者的承載篩選匯總成單一數據結構，以便與 EnableTraceEx2 函式搭配使用。 TdhAggregatePayloadFilters 會配置並填入匯總承載篩選條件的不透明數據結構。不再需要匯總承載篩選條件時， TdhCleanupPayloadEventFilterDescriptor 函式會用來釋放傳回之EVENT_FILTER_DESCRIPTOR 結構中已配置給匯總承載篩選的記憶體。

範例

如需使用 TdhAggregatePayloadFilters 函式來匯總承載篩選以用於篩選記錄器會話中特定條件的範例，請參閱 EnableTraceEx2 函式的範例。

規格需求

需求	值
最低支援的用戶端	Windows 8.1 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2012 R2 [僅限傳統型應用程式]
目標平台	Windows
標頭	tdh.h
程式庫	Tdh.lib
Dll	Tdh.dll