MINIPORT_RESET回呼函式 (ndis.h)

發行項
02/29/2024

警告

所有 NDIS 6.83 和更新版本的驅動程式都不建議 使用 MiniportResetEx 和 MiniportCheckForHangEx 回呼函式。如需詳細資訊，請參閱 NDIS 6.83 和更新版本中的 Check-for-Hang 和 Reset 作業。

NDIS 會呼叫 NDIS 迷你埠驅動程式的 MiniportResetEx 函式，以起始網路介面卡重設 (NIC) 。如需詳細資訊，請參閱 Miniport 配接器檢查-for-Hang 和 Reset 作業和 Miniport 驅動程式硬體重設。

注意 NDIS 迷你埠驅動程式可以使用 MINIPORT_RESET 類型來宣告此函式。

語法

MINIPORT_RESET MiniportReset;

NDIS_STATUS MiniportReset(
  [in]  NDIS_HANDLE MiniportAdapterContext,
  [out] PBOOLEAN AddressingReset
)
{...}

參數

[in] MiniportAdapterContext

迷你埠驅動程式在其 MiniportInitializeEx 函式中配置的內容區域句柄。迷你埠驅動程式會使用此內容區域來維護迷你埠配接器的狀態資訊。

[out] AddressingReset

布爾變數的指標。如果 NDIS 應該呼叫 MiniportOidRequest 函式，將這個變數設定為 TRUE，以將尋址和其他組態設定還原至目前的值。如需詳細資訊，請參閱硬體重設。

傳回值

MiniportResetEx 可以傳回下列其中一個狀態值：

傳回碼	Description
NDIS_STATUS_SUCCESS	MiniportResetEx 已成功將迷你埠適配卡重設為操作狀態。
NDIS_STATUS_PENDING	驅動程式會在作業完成時呼叫 NdisMResetComplete 函式，以異步方式完成重設作業。
NDIS_STATUS_RESET_IN_PROGRESS	MiniportResetEx 判斷迷你埠配接器目前正在重設，因此此呼叫是多餘的。
NDIS_STATUS_SOFT_ERRORS	MiniportResetEx 已成功重設迷你埠適配卡，但在作業期間發生可復原的錯誤。 MiniportResetEx 應該已呼叫 NdisWriteErrorLogEntry 函式，並具有錯誤的詳細資訊。
NDIS_STATUS_HARD_ERRORS	MiniportResetEx 嘗試重設迷你埠適配卡，但在作業期間發生無法復原的錯誤。 MiniportResetEx 應該已呼叫 NdisWriteErrorLogEntry ，其中包含錯誤的詳細資訊。

備註

驅動程式會在呼叫時指定 MiniportResetEx 進入點 NdisMRegisterMiniportDriver 函式。

中繼驅動程式不需要 MiniportResetEx。

MiniportResetEx 可以重設迷你埠配接器的參數。如果重設會導致迷你埠適配卡的月臺位址變更，迷你埠驅動程式會在重設完成後自動還原站臺位址的先前值。硬體重設的任何多播或功能尋址遮罩，不需要在此函式中重設。

如果重設作業變更其他資訊，例如多播或功能尋址資訊， MiniportResetEx 必須先將 AddressingReset 上的變數設定為 TRUE ，才能傳回。這會導致 NDIS 呼叫 MiniportOidRequest 函式來還原資訊。 NDIS 也會藉由呼叫 OID_PNP_ADD_WAKE_UP_PATTERN 來還原網路喚醒 (WoL) 模式清單。驅動程式應該從配接器內容釋出 WoL 模式清單，因為硬體清單已經重設。

NDIS 不會中止任何擱置的 OID 要求或傳送要求。如果驅動程式可以在重設之後安全地完成擱置的 OID 或傳送要求，驅動程式可以保留擱置的 OID 或傳送要求，直到重設作業完成為止。否則，驅動程式應該藉由呼叫 NdisMOidRequestComplete 或來完成擱置的 OID 或傳送要求 NdisMSendNetBufferListsComplete 函式分別在 MiniportResetEx 傳 回之前。

注意從 NDIS 6.30 開始，迷你埠驅動程式在重設作業完成之前，不得保留擱置的 OID 或傳送要求。相反地，驅動程式必須在重設作業完成之前，分別呼叫 NdisMOidRequestComplete 或 NdisMSendNetBufferListsComplete 函式來完成這些擱置的要求。如果驅動程式以異步方式完成重設作業，它必須完成擱置的 OID，並在驅動程式呼叫 NdisMResetComplete 之前傳送要求。

迷你埠驅動程式不應該呼叫 NdisMIndicateStatusEx 函式，以發出每個重設作業的開始和完成訊號。 NDIS 會在重設開始和結束時通知系結通訊協定驅動程式。

如果 MiniportResetEx 必須在重設作業期間等候迷你埠配接器中的狀態變更，它可以呼叫 NdisStallExecution 函式。不過，
MiniportResetEx 函式不得呼叫 NdisStallExecution ，其時間間隔大於 50 毫秒。如果驅動程式必須等候超過 50 毫秒 (，或者如果輪詢) ，它應該改為設定定時器並傳回NDIS_STATUS_PENDING。

如果 MiniportResetEx 傳回NDIS_STATUS_PENDING，驅動程式必須藉由呼叫 NdisMResetComplete 函式來完成重設。

如果迷你埠適配卡處於 MediaConnectStateConnected 狀態，且其狀態因為重設而變更，包括 MediaConnectStateUnknown 狀態的變更，迷你埠驅動程式必須回報狀態變更，並具有 NDIS_STATUS_LINK_STATE 狀態指示。迷你埠驅動程式也必須指出重設之後重新建立連結時的 MediaConnectStateConnected 狀態指示。

MiniportResetEx 可以先占中斷。

NDIS 會定期呼叫 MiniportCheckForHangEx 函式，以判斷它是否應該呼叫 MiniportResetEx。呼叫 MiniportCheckForHangEx 的預設逾時為 2 秒。如果此預設值太短，迷你埠驅動程式可以在呼叫時設定較大的 CheckForHangTimeInSeconds 值
NdisMSetMiniportAttributes 函式在初始化期間。如需詳細資訊，請參閱 Miniport 配接器檢查-for-Hang 和重設作業。

NDIS 無法判斷 NIC 是否已停止回應接收作業。若要處理這類失敗， MiniportCheckForHangEx 函式可以監視接收作業，並視需要傳回 TRUE 以強制重設。迷你埠也可以呼叫 NdisMResetMiniport 來要求重設。

NDIS 會在 IRQL <= DISPATCH_LEVEL呼叫 MiniportResetEx。

例子

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

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

MINIPORT_RESET MyResetEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyResetEx(
    NDIS_HANDLE  MiniportAdapterContext,
    PBOOLEAN  AddressingReset
    )
  {...}

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

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