MINIPORT_ADD_DEVICE回呼函式 (ndis.h)

發行項
02/26/2024

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

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

傳回碼	Description
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 參數指向的結構。

如果 Miniport 驅動程式在配置內容區域之後， MiniportAddDevice 呼叫失敗，驅動程式必須先釋放內容區域，才能從 MiniportAddDevice 傳回。

迷你埠驅動程式應該針對 NDIS_MINIPORT_ADD_DEVICE_REGISTRATION_ATTRIBUTES 結構的 MiniportAddDeviceContext 成員，以及 NDIS_MINIPORT_INIT_PARAMETERS 結構的 MiniportAdapterContext 成員使用不同的內容區域。個別的內容區域可確保內容區域中的資訊不會重新初始化，如果迷你埠配接器已停止並重新初始化，則可能會發生在 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的詳細資訊，請參閱標註函式行為。