FILTER_ATTACH回呼函式 (ndis.h)

發行項
02/26/2024

NDIS 會呼叫篩選驅動程式的 FilterAttach 函式，以配置和初始化篩選模組的數據結構。

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

語法

FILTER_ATTACH FilterAttach;

NDIS_STATUS FilterAttach(
  [in] NDIS_HANDLE NdisFilterHandle,
  [in] NDIS_HANDLE FilterDriverContext,
  [in] PNDIS_FILTER_ATTACH_PARAMETERS AttachParameters
)
{...}

參數

[in] NdisFilterHandle

識別篩選模組的 NDIS 句柄。篩選驅動程式必須儲存此句柄。後續呼叫 NdisFXxx 函式時需要句柄。

[in] FilterDriverContext

驅動程式傳遞至的句柄 NdisFRegisterFilterDriver 函式，可識別驅動程式內容區域。

[in] AttachParameters

的指標 NDIS_FILTER_ATTACH_PARAMETERS 定義篩選模組之初始化參數的結構。

傳回值

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

傳回碼	Description
NDIS_STATUS_SUCCESS	FilterAttach 已成功為此篩選模組配置和初始化數據結構。
NDIS_STATUS_RESOURCES	FilterAttach 失敗，因為資源不足。
NDIS_STATUS_FAILURE	如果上述值都未套用，FilterAttach 會傳回NDIS_STATUS_FAILURE。篩選驅動程序應該呼叫 NdisWriteEventLogEntry 函式以及指定失敗原因的參數。

備註

FilterAttach 是必要的函式。當指定的篩選模組處於中斷鏈接狀態時，NDIS 會呼叫篩選驅動程式的 FilterAttach 函式。在 FilterSetOptions 函式的呼叫傳回之後，NDIS 可以隨時呼叫 FilterAttach。

在 FilterAttach 中開始執行時，篩選模組會進入附加狀態。

篩選驅動程序應該避免發出不必要的 OID 查詢。請改用中的資訊NDIS_FILTER_ATTACH_PARAMETERS可用時，取得基礎驅動程式的相關信息。

篩選驅動程式會在 NDIS 呼叫 FilterAttach 時執行下列作業。

建立篩選模組的內容區域，並配置緩衝池和任何其他資源。
將 NdisFSetAttributes 函式與 NDIS 傳遞至 FilterAttach 的 NdisFilterHandle 一起呼叫。 NdisFSetAttributes 的 FilterModuleContext 參數會指定此篩選模組的篩選驅動程式內容區域。 NDIS 會將此內容區域傳遞至篩選驅動程式的 FilterXxx 函式。
選擇性地從登錄讀取組態參數。
如果上述作業成功完成，篩選模組會進入暫停狀態。
如果上述作業失敗，篩選驅動程式必須釋放它在 FilterAttach 函式中配置的任何資源，並將篩選模組傳回至 [中斷連結 ] 狀態。
傳回NDIS_STATUS_SUCCESS或適當的失敗碼。

篩選驅動程式不應該發出傳送要求、指出已接收的數據、提出 OID 要求，或從附加狀態提出狀態指示。

NDIS 會呼叫篩選驅動程式的 FilterDetach 函式，以釋放與篩選模組相關聯的所有資源，並將篩選模組傳回中斷鏈接狀態。

NDIS 會在 IRQL 呼叫 FilterAttach = PASSIVE_LEVEL。

例子

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

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

FILTER_ATTACH MyAttach;

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

_Use_decl_annotations_
NDIS_STATUS
 MyAttach(
    NDIS_HANDLE  NdisFilterHandle,
    NDIS_HANDLE  FilterDriverContext,
    PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    )
  {...}

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

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