Zarządzanie obiektami

W tej sekcji opisano prawidłowe użycie typów obiektów interfejsu API platformy filtrowania systemu Windows (WFP).

Sesji

Interfejs API WFP jest zorientowany na sesję, a większość wywołań funkcji jest wykonywana w kontekście sesji. Nowa sesja klienta jest tworzona przez wywołanie FwpmEngineOpen0. Sesja kończy się, gdy klient wywołuje FwpmEngineClose0 lub proces klienta kończy się. Gdy sesja zostanie zniszczona, celowo lub przez uruchomienie RPC, aparat filtrowania podstawowego (BFE) po raz pierwszy przerywa dowolną istniejącą transakcję.

Podczas tworzenia nowej sesji obiekt wywołujący może utworzyć sesję dynamiczną, przekazując flagę FWPM_SESSION_FLAG_DYNAMIC do FwpmEngineOpen0. Wszystkie obiekty dodane podczas sesji dynamicznej są automatycznie usuwane po zakończeniu sesji.

Transakcji

Interfejs API WFP jest transakcyjny, a większość wywołań funkcji jest wykonywana w kontekście transakcji. Wywołujące mogą używać FwpmTransactionBegin0, FwpmTransactionCommit0i FwpmTransactionAbort0 jawnie kontrolować transakcje. Jeśli jednak wywołanie funkcji zostanie wykonane poza jawną transakcją, zostanie wykonane w ramach niejawnej transakcji. Jeśli transakcja jest w toku, po zakończeniu sesji zostanie ona automatycznie przerwana. Niejawne transakcje nigdy nie są wymuszane.

Transakcje są tylko do odczytu lub odczytu/zapisu i wymuszają rygorystyczne izolowane na poziomie atomowym trwałe (ACID) semantyki.

Każda sesja klienta może mieć w toku tylko jedną transakcję w danym momencie. Jeśli obiekt wywołujący próbuje rozpocząć drugą transakcję przed zatwierdzeniem lub przerwaniem pierwszego, funkcja BFE zwróci błąd.

Jeśli operacja zakończy się niepowodzeniem w trakcie transakcji, nie ma to wpływu na ogólny stan transakcji. Załóżmy na przykład, że klient rozpoczyna transakcję i pomyślnie wywołuje FwpmFilterAdd0 trzy razy przed niepowodzeniem czwartego wywołania. Klient ma teraz następujące możliwości:

• Przerwanie transakcji, w tym przypadku żadna z filtrów nie zostanie dodana.
• Zatwierdzanie transakcji, w tym przypadku zostaną dodane pierwsze trzy filtry.
• Kontynuuj wykonywanie kolejnych operacji, w tym potencjalnie ponawianie próby niepowodzenia FwpmFilterAdd0.

Po rozpoczęciu transakcji usługa BFE będzie czekać, aż sesji txnWaitTimeoutInMSec wygaśnie, aby uzyskać blokadę. Jeśli blokada nie zostanie uzyskana w tym czasie, przejęcie blokady (a wywołanie FwpmTransactionBegin0) zakończy się niepowodzeniem. Uniemożliwia to klientom nieokreślone reagowanie. Jeśli klient nie określił limitu czasu blokady, wartość domyślna to 15 sekund.

Każda transakcja ma również limit czasu blokady. Jest to maksymalny czas, przez który może być właścicielem blokady. Jeśli właściciel nie zwolni blokady w tym czasie, transakcja zostanie wymuszona, powodując zwolnienie blokady. Limit czasu blokady nie jest konfigurowalny. Jest nieskończona dla wywołań trybu jądra i jedna godzina dla wywołujących tryb użytkownika. Jeśli transakcja zostanie wymuszona, następne wywołanie wykonane w ramach tej transakcji zakończy się niepowodzeniem z FWP_E_TXN_ABORTED.

Okresy istnienia obiektów

Obiekty mogą mieć jeden z czterech możliwych okresów istnienia:

• Dynamiczny — obiekt jest dynamiczny tylko wtedy, gdy jest dodawany przy użyciu dojścia sesji dynamicznej. Obiekty dynamiczne będą aktywne, dopóki nie zostaną usunięte lub sesja będąca właścicielem zakończy się.
• Statyczne — obiekty są domyślnie statyczne. Obiekty statyczne są aktywne do momentu ich usunięcia, zatrzymanie protokołu BFE lub zamknięcie systemu.
• Trwałe — obiekty trwałe są tworzone przez przekazanie odpowiedniej flagi FWPM_*_FLAG_PERSISTENT do funkcji Fwpm*Add0. Trwałe obiekty będą aktywne do momentu ich usunięcia.
• Wbudowane — wbudowane obiekty są wstępnie zdefiniowane przez protokół BFE i nie można ich dodawać ani usuwać. Żyją na zawsze.

Filtry w warstwach trybu jądra można oznaczyć jako filtry czasu rozruchu, przekazując odpowiednią flagę do FwpmFilterAdd0. Filtry czasu rozruchu są dodawane do systemu po uruchomieniu sterownika TCP/IP i usuwane po zakończeniu inicjowania BFE. Obiekty trwałe są dodawane podczas uruchamiania protokołu BFE.

W wielu przypadkach dostawca zasad może nie chcieć, aby jego trwałe zasady były wymuszane, jeśli dostawca został wyłączony. Podczas dodawania dostawcy obiekt wywołujący może określić opcjonalną nazwę usługi systemu Windows. Podczas dodawania obiektów trwałych obiekt wywołujący może opcjonalnie określić dostawcę, który jest właścicielem tego obiektu. Na początku usługi BFE dodaje do systemu tylko trwałe obiekty, jeśli nie są skojarzone z dostawcą, lub skojarzony dostawca nie ma nazwy usługi systemu Windows lub skojarzona usługa systemu Windows jest ustawiona na automatyczne uruchamianie.

Skojarzenia obiektów

Niektóre obiekty mają odwołania do innych obiektów. Na przykład filtr zawsze odwołuje się do warstwy i może odwoływać się do objaśnień i kontekstu dostawcy. Obiekty nie mogą odwoływać się do obiektów, które mogą mieć krótszy okres istnienia. W związku z tym obiekt dynamiczny nie może odwoływać się do obiektu dynamicznego z innej sesji. Obiekt statyczny nie może odwoływać się do obiektu dynamicznego. Obiekt trwały nie może odwoływać się do obiektu dynamicznego, obiektu statycznego lub trwałego obiektu należącego do innego dostawcy.

Nie można usunąć obiektu, dopóki nie zostaną usunięte wszystkie obiekty odwołujące się do niego po raz pierwszy.

Identyfikatory LUN i identyfikatory GUID

Wszystkie obiekty interfejsu API WFP trybu użytkownika (FWPM) są identyfikowane przez globalnie unikatowy identyfikator (identyfikator GUID) i odwoływać się do innych obiektów przez ich identyfikator GUIDs. Identyfikator GUI D musi być unikatowy tylko w obrębie typu obiektu. Na przykład filtr i kontekst dostawcy mogą mieć taki sam identyfikator GUID, ale nie można wykonać dwóch filtrów. Podczas dodawania nowego obiektu obiekt wywołujący może przypisać identyfikator GUID obiektu lub pozostawić go bez inicjowania i umożliwić usłudze BFE przypisanie identyfikatora GUID .

Wszystkie obiekty interfejsu API WFP trybu jądra (FWPS) są identyfikowane przez lokalnie unikatowy identyfikator (LUID) i odwoływać się do innych obiektów za pomocą identyfikatora LUID. Przełącznik z identyfikatora GUID do LUID umożliwia programowi WFP oszczędzanie niestronicowanej puli i optymalizowanie przetwarzania w czasie wykonywania. Szerokość LUID zależy od typu obiektu i zakresów od UINT16 do UINT64. identyfikatory LUIDsą zawsze przypisywane przez interfejs BFE.