SET_OPTIONS回呼函式 (ndis.h)

  • 發行項

NDIS 會呼叫驅動程式的 XxxSetOptions 函式，以允許驅動程式註冊選擇性服務。 此函式定義為 迷你埠驅動程式的 MiniportSetOptions 、通訊協定驅動程式的 ProtocolSetOptions ，或篩選驅動程式的 FilterSetOptions 。

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

語法

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

參數

[in] NdisDriverHandle

識別驅動程式的句柄。 當驅動程式從驅動程式註冊函式傳回時，NDIS 會傳回此句柄， (迷你埠驅動程式的 NdisMRegisterMiniportDriver、通訊協定驅動程式的 NdisRegisterProtocolDriver，以及篩選驅動程式的 NdisFRegisterFilterDriver) 。

[in] DriverContext

驅動程式傳遞給識別驅動程式內容區域的 NdisRegisterXxxDriver 句柄，其中 Xxx 是驅動程式類型 (Miniport、Protocol 或 Filter) 。

傳回值

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

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

備註

XxxSetOptions 是選擇性函式。 NDIS 會在驅動程式呼叫 的內容中呼叫 XxxSetOptions NdisRegisterXxxDriver 函 式，其中 Xxx 是 Miniport、Protocol 或 Filter () 的驅動程序類型。

XxxSetOptions 會註冊選擇性服務，並可配置其他驅動程序資源。 若要註冊選用 的MiniportXxx、 ProtocolXxx或 FilterXxx 函式，驅動程式會呼叫 NdisSetOptionalHandlers 函 式。 驅動程式會在 NdisSetOptionalHandlers 的 NdisHandle 參數上，從 NdisDriverHandle 參數傳遞句柄，並在 OptionalHandlers 參數傳遞特性結構。

迷你埠驅動程式可以套用至下列特性結構中定義的選擇性服務：

NDIS_MINIPORT_CO_CHARACTERISTICS
NDIS_MINIPORT_PNP_CHARACTERISTICS
NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS
NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS (請參閱 NDIS 6.0 TCP chimney 卸除檔)
NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS ( 請參閱 NDIS 6.0 TCP chimney 卸除檔)

通訊協定驅動程式可以套用至下列特性結構中定義的選擇性服務：

NDIS_PROTOCOL_CO_CHARACTERISTICS
NDIS_CO_CLIENT_OPTIONAL_HANDLERS
NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

目前 Windows 版本中沒有選擇性的篩選驅動程式服務。

NDIS 可以在 XxxSetOptions 傳回之後，隨時呼叫驅動程式的其他 MiniportXxx、ProtocolXxx 或 FilterXxx 函式。 驅動程式應該準備好在其初始化函式中回呼： (MiniportInitializeEx for miniport drivers、 ProtocolBindAdapterEx 用於通訊協定驅動程式，以及篩選驅動程式的 FilterAttach) 。

對於迷你埠驅動程式，迷你埠適配卡在NDIS呼叫MiniportInitializeEx之前處於「已停止」狀態。 針對通訊協議驅動程式，通訊協定系結在 NDIS 呼叫 ProtocolBindAdapterEx 之前處於未繫結狀態。 針對篩選驅動程式，篩選模組在 NDIS 呼叫 FilterAttach 之前處於中斷鏈接狀態。

如果嘗試配置資源或服務失敗， XxxSetOptions 應該復原所有成功配置，然後再傳回具有NDIS_STATUS_SUCCESS以外的狀態的控件。

迷你埠和篩選驅動程式的 XxxDriverUnload 應該復原在 XxxSetOptions 中執行的所有作業

NDIS 在 IRQL = PASSIVE_LEVEL 呼叫 XxxSetOptions 。

例子

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

在 Ndis.h 頭檔中，SET_OPTIONS回呼函式會進一步定義如下：

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);
這可讓所有 NDIS 驅動程式使用相同的語法來實作其 XxxSetOptions 回呼函式。 迷你埠驅動程式使用 MINIPORT_SET_OPTIONS 類型、通訊協定驅動程式使用 PROTOCOL_SET_OPTIONS 類型，而篩選驅動程式則使用 FILTER_SET_OPTIONS 類型。

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

MINIPORT_SET_OPTIONS MySetOptions;

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

_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

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

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

規格需求

需求 值
最低支援的用戶端 NDIS 6.0 和更新版本支援。
目標平台 Windows
標頭 ndis.h (包含 Ndis.h)
IRQL PASSIVE_LEVEL

另請參閱

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS NDIS_CO_CLIENT_OPTIONAL_HANDLERS NDIS_PROTOCOL_CO_CHARACTERISTICS

NdisOpenAdapterEx

NdisRegisterProtocolDriver

NdisSetOptionalHandlers

ProtocolBindAdapterEx