FILTER_RESTART回呼函式（ndis.h）

發行項
02/07/2025

FilterRestart 函式會起始指定篩選模組的重新啟動作業。

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

語法

FILTER_RESTART FilterRestart;

NDIS_STATUS FilterRestart(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_RESTART_PARAMETERS RestartParameters
)
{...}

參數

[in] FilterModuleContext

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

[in] RestartParameters

的指標 NDIS_FILTER_RESTART_PARAMETERS 結構，定義篩選模組的重新啟動參數。

傳回值

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

傳回碼	描述
NDIS_STATUS_SUCCESS	FilterRestart 已成功重新啟動指定的篩選模組。
NDIS_STATUS_PENDING	篩選驅動程式會在完成重新啟動作業之後，以異步方式完成要求，並呼叫 NdisFRestartComplete 函式。
NDIS_STATUS_RESOURCES	FilterRestart 因為資源不足而失敗。
NDIS_STATUS_FAILURE	上述狀態值都未套用。篩選驅動程式應呼叫 NdisWriteEventLogEntry 函式，以及指定失敗原因的參數。

言論

FilterRestart 是篩選驅動程式的必要函式。當篩選模組處於暫停狀態時，NDIS 可以呼叫 FilterRestart。篩選模組會在 FilterRestart開始執行時，輸入 重新啟動 狀態。

當 NDIS 呼叫 FilterRestart時，篩選驅動程式：

必須完成重新啟動一般傳送和接收作業所需的作業。
選擇性地讀取或寫入組態參數。
選擇性地重新配置緩衝池。
選擇性地修改在 RestartAttributes 成員中指定的重新啟動屬性 NDIS_FILTER_RESTART_PARAMETERS 結構。如果 RestartAttributes 中的指標NULL，則篩選驅動程式不應該修改或新增至重新啟動屬性清單。如果 RestartAttributes 中的指標 為非NULL，它會指向重新啟動屬性清單中的第一個 NDIS_RESTART_ATTRIBUTES 結構。如果篩選驅動程式未重新啟動，則不應該修改任何屬性。
選擇性地使用 OID 要求來查詢或設定基礎驅動程式中的資訊。篩選驅動程式不應該針對已在重新啟動屬性清單中提供的資訊發出 OID 要求。
傳回NDIS_STATUS_SUCCESS或失敗狀態。

如果篩選驅動程式修改重新啟動屬性的清單，篩選驅動程式：

如果它無法辨識 Oid Oid 成員中的 OID，則不應該修改任何媒體特定屬性 NDIS_RESTART_ATTRIBUTES 結構。
可以將新的媒體特定屬性新增至重新啟動屬性清單。在此情況下，篩選驅動程式必須配置新的NDIS_RESTART_ATTRIBUTES 結構，例如，使用 NdisAllocateMemoryWithTagPriority function--並提供新屬性的記憶體空間。將重新啟動屬性傳播至過度配置驅動程序之後，NDIS 會釋放篩選驅動程式的屬性記憶體。
可以修改重新啟動屬性清單中的媒體特定屬性。如果篩選驅動程式需要更多的記憶體空間，它可以使用 NdisFreeMemory 函式釋放 NDIS_RESTART_ATTRIBUTES 結構，並配置新的結構以包含修改的資訊。將重新啟動屬性傳播至過度配置驅動程序之後，NDIS 會釋放篩選驅動程式的屬性記憶體。
如果 NDIS_RESTART_ATTRIBUTES 結構中的 Oid 成員為，則應該為 OID_GEN_MINIPORT_RESTART_ATTRIBUTES，請確定 NDIS_RESTART_GENERAL_ATTRIBUTES 結構包含篩選驅動程式所需的資訊。若要確定NDIS_RESTART_GENERAL_ATTRIBUTES結構包含必要資訊，您應該檢查 NDIS_OBJECT_HEADER 結構中所指定 NDIS_OBJECT_HEADER 結構中修訂成員，該成員是在NDIS_RESTART_GENERAL_ATTRIBUTES結構標頭成員中指定。
注意篩選驅動程式可以修改NDIS_RESTART_GENERAL_ATTRIBUTES結構中的任何成員。如果篩選驅動程式應該修改的某些屬性未包含在 NDIS 所提供的結構修訂中，篩選驅動程式應該依賴過度配置驅動程式來發出遺漏屬性的 OID 要求。篩選驅動程式可以在完成 OID 要求時修改屬性。
如果篩選驅動程式變更重新啟動屬性，則必須提供 FilterOidRequest 函式。篩選驅動程式必須確定在重新啟動屬性中過度顯示驅動程式接收的資訊，與回應 OID 要求時收到的資訊一致。

篩選驅動程式傳回其狀態或呼叫 NdisFRestartComplete 函式之後，重新啟動作業就會完成。如果作業順利完成，篩選模組會處於 執行中 狀態，並且會繼續正常傳送和接收處理。如果重新啟動作業失敗，篩選模組會回到暫停狀態。

NDIS 會在 IRQL = PASSIVE_LEVEL 呼叫 FilterRestart。

範例

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

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

FILTER_RESTART MyRestart;

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

_Use_decl_annotations_
NDIS_STATUS
 MyRestart(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    )
  {...}

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

如需 Use_decl_annotations的相關信息，請參閱批注函式行為。