FILTER_RESTART回呼函式 (ndis.h)

發行項
02/29/2024

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 會傳回下列其中一個狀態值：

傳回碼	Description
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，則不應該修改任何媒體特定屬性 NDIS_RESTART_ATTRIBUTES 結構。
可以將新的媒體特定屬性新增至重新啟動屬性清單。在此情況下，篩選驅動程式必須配置新的NDIS_RESTART_ATTRIBUTES結構，例如，使用 NdisAllocateMemoryWithTagPriority 函式--並提供新屬性的記憶體空間。將重新啟動屬性傳播至過度配置驅動程序之後，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結構中的 Revision 成員，該成員是在NDIS_RESTART_GENERAL_ATTRIBUTES結構的 Header 成員中指定的。
注意篩選驅動程式可以修改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的詳細資訊，請參閱標註函式行為。