FILTER_PAUSE回呼函式 (ndis.h)

發行項
02/26/2024

NDIS 會呼叫篩選驅動程式的 FilterPause 函式，以起始指定之篩選模組的暫停作業。

注意您必須使用 FILTER_PAUSE 類型來宣告函式。如需詳細資訊，請參閱下列範例一節。

語法

FILTER_PAUSE FilterPause;

NDIS_STATUS FilterPause(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_PAUSE_PARAMETERS PauseParameters
)
{...}

參數

[in] FilterModuleContext

篩選驅動程式應該暫停之篩選模組的內容區域句柄。篩選驅動程式在 FilterAttach 函式中建立並初始化此內容區域。

[in] PauseParameters

的指標 NDIS_FILTER_PAUSE_PARAMETERS 定義篩選模組暫停參數的結構。

傳回值

NDIS 驅動程式無法失敗暫停要求。篩選驅動程式應該呼叫 NdisWriteEventLogEntry 函式，以及指定發生任何錯誤原因的參數。

傳回碼	Description
NDIS_STATUS_SUCCESS	FilterPause 已成功暫停指定的篩選模組。
NDIS_STATUS_PENDING	篩選驅動程式會以異步方式完成要求，並呼叫 NdisFPauseComplete 函式。

備註

FilterPause 是必要函式。當篩選模組處於執行中狀態時，NDIS 可以呼叫 FilterPause。篩選模組會在 FilterPause 函式的執行開始時進入暫停狀態。

當 NDIS 呼叫 FilterPause 時，篩選驅動程式會執行下列作業：

必須呼叫任何佇列傳送緩衝區的 NdisFSendNetBufferListsComplete 函式，這些緩衝區會過度建立驅動程式。
必須呼叫基礎驅動程式所建立之任何佇列接收緩衝區的 NdisFReturnNetBufferLists 函式。
必須等候 NDIS 傳回驅動程式源自的所有未處理傳送要求 FilterSendNetBufferListsComplete 函式。
必須等候 NDIS 傳回所有未處理的接收指示，指出驅動程式源自 FilterReturnNetBufferLists 函式。

篩選驅動程式從 FilterPause 傳回NDIS_STATUS_SUCCESS或呼叫 NdisFPauseComplete 函式之後，暫停作業就會完成。篩選模組處於 [已暫停 ] 狀態。

在暫停或暫停狀態中，篩選驅動程式應該繼續處理 OID 要求或狀態指示。驅動程式應該拒絕對它的呼叫 FilterSendNetBufferLists 函式。驅動程式可以在呼叫時傳遞至其 FilterReceiveNetBufferLists 函式。不過，驅動程式無法傳遞它所建立的任何緩衝區。驅動程式不得源自任何接收指示或傳送要求。

在 [暫停 ] 狀態中，篩選模組不得產生傳送要求或接收指示。

NDIS 會呼叫 FilterRestart 函式，以起始處於 Paused 狀態之篩選模組的重新啟動要求。

NDIS 會在 IRQL 呼叫 FilterPause = PASSIVE_LEVEL。

例子

若要定義 FilterPause 函式，您必須先提供函式宣告，以識別您要定義的函式類型。 Windows 提供一組驅動程式的函式類型。使用函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程式驗證程式 (SDV) ，以及其他驗證工具尋找錯誤，而且是撰寫 Windows 作業系統驅動程式的需求。

例如，若要定義名為「 MyPause」的 FilterPause 函式，請使用 FILTER_PAUSE 類型，如下列程式代碼範例所示：

FILTER_PAUSE MyPause;

然後，實作您的函式，如下所示：

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_PAUSE_PARAMETERS  FilterPauseParameters
    )
  {...}

FILTER_PAUSE函式類型定義於 Ndis.h 頭檔中。若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 Use_decl_annotations 批註新增至函式定義。 Use_decl_annotations批註可確保使用頭檔中套用至FILTER_PAUSE函式類型的註釋。如需函數宣告需求的詳細資訊，請參閱使用 NDIS 驅動程式的函式角色類型來宣告函式。

如需 Use_decl_annotations的詳細資訊，請參閱標註函式行為。