共用方式為

物件管理

  • 發行項

本節涵蓋正確使用 Windows 篩選平臺 （WFP） API 物件類型。

會話

WFP API 是會話導向，而且大部分的函式呼叫都是在會話的內容中進行。 呼叫 FwpmEngineOpen0建立新的客戶端會話。 當用戶端呼叫 FwpmEngineClose0 或客戶端進程終止時，會話就會結束。 當會話終結時，無論是基於目的還是由 RPC 取消，基底篩選引擎 （BFE） 會先中止任何現有的交易。

建立新的工作階段時，呼叫端可以將 FWPM_SESSION_FLAG_DYNAMIC 旗標傳遞至 FwpmEngineOpen0來建立動態工作階段。 在動態工作階段期間新增的任何物件都會在工作階段結束時自動刪除。

交易

WFP API 是交易式，而且大部分的函式呼叫都是在交易的內容中進行。 呼叫端可以使用 FwpmTransactionBegin0、FwpmTransactionCommit0，以及 FwpmTransactionAbort0 明確控制交易。 不過，如果函數調用是在明確交易之外進行，則會在隱含交易內執行。 如果交易正在進行中，當會話終止時，它會自動中止。 隱含交易永遠不會強制中止。

交易是只讀或讀取/寫入，並強制執行嚴格的不可部分完成一致隔離耐久 （ACID） 語意。

每個用戶端會話一次只能有一個交易進行中。 如果呼叫端在認可或中止第一個交易之前嘗試開始第二筆交易，BFE 會傳回錯誤。

如果作業在交易過程中失敗，則不會影響交易的整體狀態。 例如，假設客戶端開始交易，並在第四次呼叫失敗之前成功呼叫 FwpmFilterAdd0 三次。 用戶端現在有下列選項：

  • 中止交易，在此情況下，不會新增任何篩選。
  • 認可交易，在此情況下會新增前三個篩選。
  • 繼續執行更多作業，包括可能重試失敗 FwpmFilterAdd0。

開始交易時，BFE 會等到會話的 txnWaitTimeoutInMSec 到期，才能取得鎖定。 如果未在此時間內取得鎖定，鎖定擷取（且 FwpmTransactionBegin0 呼叫）將會失敗。 這可防止客戶端無限期地無法回應。 如果用戶端未指定鎖定逾時，則預設為15秒。

每個交易也有鎖定逾時。 這是可擁有鎖定的最大時間量。 如果擁有者在此時間內未釋放鎖定，交易就會強制中止，導致鎖定解除。 無法設定鎖定逾時。 對於內核模式來電者而言是無限的，而使用者模式來電者則為一小時。 如果交易強制中止，在該交易內進行的下一個呼叫將會失敗，並 FWP_E_TXN_ABORTED。

物件存留期

物件可以有四個可能的存留期之一：

  • 動態 - 只有在使用動態會話句柄新增物件時，物件才會是動態的。 動態物件會持續存在，直到刪除或擁有的會話終止為止。
  • Static - 對象預設為靜態。 靜態物件會持續存在，直到刪除、BFE 停止或系統關閉為止。
  • 持續性 - 持續性對像是藉由將適當的 FWPM_*_FLAG_PERSISTENT旗标传递至 Fwpm*Add0 函式來建立。 永續性物件會持續存在，直到刪除為止。
  • 內建 - 內建物件是由 BFE 預先定義的，且無法新增或刪除。 他們永遠活著。

核心模式層中的篩選可以透過將適當的旗標傳遞至 FwpmFilterAdd0 ，以標示為開機時間篩選。 啟動 TCP/IP 驅動程序時，開機時間篩選會新增至系統，並在 BFE 完成初始化時移除。 BFE 啟動時會新增持續性物件。

在許多情況下，如果提供者已停用，原則提供者可能不希望強制執行其持續性原則。 新增提供者時，呼叫端可以指定選擇性的 Windows 服務名稱。 新增持續性物件時，呼叫端可以選擇性地指定「擁有」該物件的提供者。 在服務啟動時，BFE 只會在與提供者沒有關聯的物件或相關聯的提供者沒有 Windows 服務名稱，或相關聯的 Windows 服務設定為自動啟動時，才會將持續性物件新增至系統。

對象關聯

某些物件具有其他對象的參考。 例如，篩選一律會參考圖層，而且可能會參考圖說文字和提供者內容。 物件不能參考可能存留期較短的物件。 因此，動態對象無法參考不同會話的動態物件。 靜態對象無法參考動態物件。 持續性對象無法參考動態物件、靜態物件或不同提供者所擁有的永續性物件。

必須先刪除參考物件的所有物件，才能刪除物件。

LUID 和 GUID

所有使用者模式 WFP API 物件 （FWPM） 都是透過全域唯一標識符來識別（GUID），並透過其 GUID來參考其他物件。 GUID 只需要在物件類型內是唯一的。 例如，篩選和提供者內容可以有相同的 GUID，但兩個篩選無法。 新增物件時，呼叫者可以指派物件的 GUID，或將它保持為零初始化，並讓 BFE 指派 GUID。

所有核心模式 WFP API 物件 （FWPS） 都是透過本機唯一標識符來識別（LUID），並依 LUID 參考其他物件。 從 GUID 切換至 LUID 可讓 WFP 節省非分頁集區，並將運行時間處理優化。 LUID 的寬度取決於物件類型和範圍，範圍從 UINT16 到 UINT64。 LUID一律由 BFE 指派。