NdisIMInitializeDeviceInstanceEx 函式 (ndis.h)

發行項
02/26/2024

NdisIMInitializeDeviceInstanceEx 函式會起始虛擬迷你埠的初始化作業，並選擇性地設定後續系結通訊協定驅動程式之虛擬迷你埠的狀態資訊。

語法

NDIS_STATUS NdisIMInitializeDeviceInstanceEx(
  [in]           NDIS_HANDLE  DriverHandle,
  [in]           PNDIS_STRING DriverInstance,
  [in, optional] NDIS_HANDLE  DeviceContext
);

參數

[in] DriverHandle

迷你埠驅動程序會處理 NdisMRegisterMiniportDriver 函式會在 NdisMiniportDriverHandle 傳回。

[in] DriverInstance

NDIS_STRING類型的指標，描述系統預設字元集中呼叫端初始化的計數位符串。此字串包含登錄機碼的名稱，驅動程式會儲存虛擬迷你埠的相關信息，也可能是系結特定資訊。對於 Microsoft Windows 2000 和更新版本的驅動程式，此字串包含 Unicode 字元。也就是說，對於 Windows 2000 和更新版本，NDIS 會將NDIS_STRING類型定義為 UNICODE_STRING 類型。

[in, optional] DeviceContext

呼叫端提供的記憶體指標，可透過驅動程式定義的裝置內容資訊來設定虛擬迷你埠，這些虛擬迷你埠之後仍可繫結至此虛擬迷你埠的較高層級通訊協定驅動程式。如果中繼驅動程式沒有這類裝置內容區域，這個參數可以是 NULL 。

傳回值

NdisIMInitializeDeviceInstanceEx 可以傳回下列其中一項：

傳回碼	Description
NDIS_STATUS_SUCCESS	NDIS 起始中繼驅動程式虛擬迷你埠的初始化作業。
NDIS_STATUS_NOT_ACCEPTED	NdisIMInitializeDeviceInstanceEx 失敗，因為 DriverHandle 指定的裝置已經初始化。

備註

NDIS 中繼驅動程序應該從其 ProtocolBindAdapterEx 函式呼叫 NdisIMInitializeDeviceInstanceEx。無法從 NDIS 中繼驅動程式呼叫 NdisIMInitializeDeviceInstanceEx ，有效地防止該驅動程式順利載入。

在呼叫 NdisIMInitializeDeviceInstanceEx 之前，中繼驅動程式的 ProtocolBindAdapterEx 函式應該系結至中繼驅動程序運作所需的任何基礎迷你埠驅動程式。 ProtocolBindAdapterEx 函式也可以配置 DeviceContext 的區域，也可以使用中繼驅動程序判斷基礎迷你埠配接器功能的相關信息進行設定，以及 ProtocolBindAdapterEx 所收集的功能。中繼驅動程式的 MiniportInitializeEx 函式後續可能會使用這類資訊來設定此內容區域，以及驅動程式虛擬迷你埠的相關信息。

中繼驅動程式對 NdisIMInitializeDeviceInstanceEx 的呼叫會導致 NDIS 呼叫中繼驅動程式的 MiniportInitializeEx 函式，如果 NDIS 收到 IRP_MN_START_DEVICE IRP 來啟動裝置。如果 NDIS 未收到這類 IRP，NDIS 將不會呼叫中繼驅動程式的 MiniportInitializeEx 函 式。

MiniportInitializeEx 的呼叫可以在稍後發生，因此不一定是在呼叫 NdisIMInitializeDeviceInstanceEx 的內容中。如果 NDIS 永遠不會針對呼叫 NdisIMInitializeDeviceInstanceEx 中所參考的虛擬迷你埠呼叫 MiniportInitializeEx，而且中繼驅動程式不再需要虛擬迷你埠，中繼驅動程式應該呼叫 NdisIMCancelInitializeDeviceInstance 函式可取消虛擬迷你埠的初始化。例如，假設中繼驅動程式會建立虛擬迷你埠，以回應成功系結至基礎迷你埠配接器。如果在 NDIS 呼叫 MiniportInitializeEx 之前移除該系結，中繼驅動程式應該呼叫 NdisIMCancelInitializeDeviceInstance 來取消虛擬迷你埠的初始化。

MiniportInitializeEx 會配置驅動程式執行網路 I/O 作業所需的任何資源，例如呼叫 NdisMSetMiniportAttributes 函式，並將驅動程式的虛擬迷你埠初始化為操作狀態。然後，當中繼驅動程式的初始化成功完成時，較高層級的通訊協定驅動程式可以自行系結至其虛擬迷你埠。

在 MiniportInitializeEx 傳回控制權之後，中繼驅動程式的裝置內容區域，如果有的話，可以包含任何中繼驅動程式定義的數據，而該數據隨後會啟用系結至相同虛擬迷你埠的所有較高層級通訊協定驅動程式，以存取該內容區域中的資訊。這類較高層級的通訊協定驅動程式可以使用查詢中繼驅動程式提供的裝置內容 NdisIMGetBindingContext 函式。

在 NDIS 呼叫中繼驅動程式的 MiniportInitializeEx 函 式之前，驅動程式可以呼叫 NdisIMCancelInitializeDeviceInstance 取消初始化作業。

在 NDIS 呼叫中繼驅動程式的 MiniportInitializeEx 函式之後，驅動程式必須呼叫 NdisIMDeInitializeDeviceInstance 以反轉初始化作業。

規格需求

需求	值
最低支援的用戶端	(支援 NDIS 6.0 和 NDIS 5.1 驅動程式，請參閱 Windows Vista 中的 NdisIMInitializeDeviceInstanceEx (NDIS 5.1) ) 。 (支援 NDIS 5.1 驅動程式，請參閱 Windows XP 中的 NdisIMInitializeDeviceInstanceEx (NDIS 5.1) ) 。
目標平台	桌面
標頭	ndis.h (包含 Ndis.h)
程式庫	Ndis.lib
IRQL	PASSIVE_LEVEL
DDI 合規性規則	Irql_IM_Function ()