FILTER_ATTACH回呼函式（ndis.h）

發行項
02/07/2025

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

Note 您必須使用 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 會傳回下列其中一個狀態值：

傳回碼	描述
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 = PASSIVE_LEVEL 呼叫 filterAttach。

範例

若要定義 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的相關信息，請參閱批注函式行為。