MINIPORT_ADD_DEVICE回呼函式（ndis.h）

發行項
02/07/2025

MiniportAddDevice 函式可讓迷你埠驅動程式為新增的裝置建立內容區域。

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

語法

MINIPORT_ADD_DEVICE MiniportAddDevice;

NDIS_STATUS MiniportAddDevice(
  [in] NDIS_HANDLE NdisMiniportHandle,
  [in] NDIS_HANDLE MiniportDriverContext
)
{...}

參數

[in] NdisMiniportHandle

NDIS 句柄，可識別即插即用（PnP）管理員正在新增的迷你埠配接器。 NDIS 也會將此句柄傳遞至 MiniportInitializeEx 函式。

[in] MiniportDriverContext

驅動程式所配置內容區域的句柄，其中驅動程式會維護狀態和組態資訊。迷你埠驅動程式已將此內容區域傳遞至 NdisMRegisterMiniportDriver 函式。

傳回值

MiniportAddDevice 會傳回下列其中一個值：

傳回碼	描述
NDIS_STATUS_SUCCESS	迷你埠驅動程式已成功配置新增裝置所需的資源。
NDIS_STATUS_RESOURCES	迷你埠驅動程式無法配置必要的資源。
NDIS_STATUS_FAILURE	MiniportAddDevice 因資源不足的原因而失敗。

如果 MiniportAddDevice 失敗，NDIS 將不會呼叫 MiniportInitializeEx 函式來初始化迷你埠配接器。

言論

MiniportAddDevice 函式是選擇性函式。支援 MSI-X 的迷你埠驅動程序應該在中指定此函式的進入點 NDIS_MINIPORT_PNP_CHARACTERISTICS 結構。

MiniportAddDevice 可以配置內容區域來處理 IRP_MN_FILTER_RESOURCE_REQUIREMENTS I/O 要求封包（IRP） MiniportFilterResourceRequirements 函式句柄。迷你埠驅動程序藉由初始化來指定內容區域 NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES 結構，然後呼叫 NdisMSetMiniportAttributes 函式。 NDIS 稍後會提供此內容句柄給 MiniportRemoveDevice、 MiniportFilterResourceRequirements、MiniportStartDevice和 MiniportInitializeEx 函式。針對 MiniportInitializeEx，內容句柄會傳遞至 MiniportAddDeviceContext 成員。 NDIS_MINIPORT_INIT_PARAMETERSMiniportInitParameters 參數所指向的結構。

如果迷你埠驅動程式在配置內容區域之後，MiniportAddDevice 呼叫失敗，驅動程式必須在從 MiniportAddDevice傳回之前釋放內容區域。

Miniport 驅動程式應該針對 NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES 結構的 MiniportAddDeviceContext 成員，以及 MiniportAdapterContextNDIS_MINIPORT_INIT_PARAMETERS 結構的成員使用不同的內容區域。個別的內容區域可確保內容區域中的資訊不會重新初始化，如果迷你埠配接器停止並重新初始化，則可能發生在 MiniportInitializeEx 函式中。

當 PnP 管理員要求 NDIS 移除裝置時，NDIS 會呼叫 MiniportRemoveDevice 函式，以復原 MiniportAddDevice 執行的作業。

NDIS 會在 IRQL = PASSIVE_LEVEL 呼叫 MiniportAddDevice。

範例

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

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

MINIPORT_ADD_DEVICE MyAddDevice;

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

_Use_decl_annotations_
NDIS_STATUS
 MyAddDevice(
    NDIS_HANDLE  NdisMiniportHandle,
    NDIS_HANDLE  MiniportDriverContext
    )
  {...}

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

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