FILTER_SET_MODULE_OPTIONS回呼函式 (ndis.h)

發行項
03/01/2024

FilterSetModuleOptions 函式會變更與指定篩選模組相關聯的選擇性服務集。

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

語法

FILTER_SET_MODULE_OPTIONS FilterSetModuleOptions;

NDIS_STATUS FilterSetModuleOptions(
  [in] NDIS_HANDLE FilterModuleContext
)
{...}

參數

[in] FilterModuleContext

此要求目標之篩選模組的內容區域句柄。篩選驅動程式已在 FilterAttach 函式中建立並初始化此內容區域。

傳回值

FilterSetModuleOptions 會傳回下列其中一個狀態值：

傳回碼	Description
NDIS_STATUS_SUCCESS	FilterSetModuleOptions 已成功註冊篩選模組的選擇性服務和資源。
NDIS_STATUS_RESOURCES	FilterSetModuleOptions 無法配置篩選模組所需的資源。
NDIS_STATUS_ XXX 或 NTSTATUS_ XXX	篩選驅動程式嘗試註冊選項失敗。這類錯誤狀態通常會從 NdisXxx 函式或核心模式支援例程傳播。

備註

如果已定義 FilterSetModuleOptions，NDIS 會先呼叫 FilterSetModuleOptions ，再呼叫 FilterRestart 函式來啟動篩選模組。

篩選驅動程式會指定傳遞給 NDIS_FILTER_DRIVER_CHARACTERISTICS 結構中可變更篩選模組選項的預設值 NdisFRegisterFilterDriver 函式在驅動程式初始化期間。

若要在運行時間變更特定篩選模組的選項，篩選驅動程式也必須在中指定 FilterSetModuleOptions 的進入點 NDIS_FILTER_DRIVER_CHARACTERISTICS 結構。

若要指定應該變更的選項， FilterSetModuleOptions 會定義特性結構，並呼叫 NdisSetOptionalHandlers 函式。篩選驅動程式不得從不同的線程呼叫 NdisSetOptionalHandlers 。

可從 FilterSetModuleOptions 指定的可能特性結構如下：

NDIS_FILTER_PARTIAL_CHARACTERISTICS NDIS_CLIENT_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS NDIS_CLIENT_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS

如需最後四個結構的資訊，請參閱 NDIS 6.0 TCP chimney 卸除檔。

每個特性結構中指定的選項可以針對每個篩選模組不同。

當 NDIS 呼叫 FilterDetach 函式時，篩選驅動程式應該復原 FilterSetModuleOptions 中執行的所有作業。

NDIS 會在 IRQL = PASSIVE_LEVEL呼叫 FilterSetModuleOptions 。

例子

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

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

FILTER_SET_MODULE_OPTIONS MySetModuleOptions;

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

_Use_decl_annotations_
NDIS_STATUS
 MySetModuleOptions(
    NDIS_HANDLE  FilterModuleContext
    )
  {...}

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

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