NdisMRegisterDevice 函式 (ndis.h)

注意 NDIS 5. x 已被取代，並被 NDIS 6 取代。 x。 如需新的 NDIS 驅動程式開發，請參閱 從 Windows Vista 開始的網路驅動程式。 如需移植 NDIS 5 的相關信息。 x 驅動程式至 NDIS 6。 x，請參閱 將 NDIS 5.x 驅動程式移植到 NDIS 6.0。

NdisMRegisterDevice 函式會建立具名裝置物件，以及裝置物件與該裝置用戶可見名稱之間的符號連結。

語法

NDIS_STATUS NdisMRegisterDevice(
  [in]  NDIS_HANDLE      NdisWrapperHandle,
  [in]  PNDIS_STRING     DeviceName,
  [in]  PNDIS_STRING     SymbolicName,
  [in]  PDRIVER_DISPATCH *MajorFunctions,
  [in]  PDEVICE_OBJECT   *pDeviceObject,
  [out] NDIS_HANDLE      *NdisDeviceHandle
);

參數

[in] NdisWrapperHandle

指定 NdisMInitializeWrapper 所傳回的句柄。

[in] DeviceName

NDIS_STRING類型的指標，其中包含命名裝置物件的 Null 終止 Unicode 字串。 字串必須是完整路徑名稱，例如 \Device\DeviceName。 針對 Windows 2000 和更新版本，NDIS 會將NDIS_STRING類型定義為 UNICODE_STRING 類型。

[in] SymbolicName

NDIS_STRING類型的指標，其中包含已註冊之裝置的 Win32 可見名稱的 Unicode 字串。 一般而言， SymbolicName 的格式如下： \DosDevices\SymbolicName。

[in] MajorFunctions

設備驅動器分派例程之一或多個進入點陣列的指標。 驅動程式必須設定與驅動程式針對裝置對象處理IRP_MJ_XXX 代碼相同的個別分派進入點。 每個分派例程都會宣告如下：

NTSTATUS
(*PDRIVER_DISPATCH) (
    IN PDEVICE_OBJECT Device Object,
    IN PIRP Irp
)   ;

驅動程式不得提供 隨插即用 或電源管理處理程式的進入點，因為已建立的裝置物件不適用於實體裝置，因此不會收到 隨插即用 或電源管理 IRP。

[in] pDeviceObject

如果呼叫成功，則為新建立之裝置物件的指標。

[out] NdisDeviceHandle

呼叫端提供的變數指標，如果函式成功，則會傳回裝置物件的句柄。 此句柄是驅動程序後續呼叫 之 NdisMDeregisterDevice 函式的必要參數。

傳回值

如果呼叫端不是 NDIS 迷你埠驅動程式 NDIS_STATUS_NOT_SUPPORTED，則 NdisMRegisterDevice 會傳回STATUS_SUCCESS，如果呼叫端不是 NDIS 迷你埠驅動程式，則傳回失敗碼。

備註

中繼驅動程式或迷你埠驅動程式可能需要個別的獨立裝置物件。 例如，中繼迷你埠驅動程式可能需要獨立裝置物件，才能在 NIC 的迷你埠驅動程式未啟動並執行時監視基礎 NIC 的狀態。 若要在這種情況下取得 NIC 的狀態，使用者模式應用程式或環境子系統會將 IRP 傳送至裝置物件。 中繼驅動程式會處理 IRP。 如果沒有獨立裝置物件，只有 NIC 的迷你埠驅動程式已啟動並執行時，才能使用 NIC 的狀態。

中繼驅動程式或迷你埠驅動程式會在 DriverEntry 呼叫 NdisMInitializeWrapper 之後，從其 DriverEntry 函式呼叫 NdisMRegisterDevice 來建立裝置物件。 NdisMRegisterDevice 會建立具名裝置物件，以及裝置物件名稱與該裝置用戶可見名稱之間的符號連結。 如果 呼叫 NdisMRegisterDevice 成功，I/O 管理員會在非分頁集區中配置裝置物件本身的記憶體，以及與裝置對象相關聯的所有其他數據結構，包括驅動程式的裝置擴充功能。 使用 NdisMRegisterDevice 所建立物件的裝置擴充功能會保留供 NDIS 使用，且驅動程式無法使用。

使用 NdisMRegisterDevice 函式建立的裝置物件，與使用 IoCreateDevice 和 IoCreateSymbolicLink 建立的裝置物件和符號連結相同。 迷你埠驅動程式負責處理它為裝置物件接收的所有 IRP。 (NDIS 會處理傳送至裝置物件的所有 隨插即用 和電源管理 IRP。) 驅動程式會使用在 NdisMRegisterDevice 提供 MajorFunctions 指標時所註冊的分派例程來處理傳送至裝置物件的 IRP。 如需裝置物件、IRP 和分派例程的詳細資訊，請參閱 裝置物件和裝置堆疊、 處理 IRP 和 寫入分派例程。

NDIS 迷你埠和中繼驅動程式不應該呼叫 IoCreateDevice 或 IoCreateSymbolicLink。 相反地，如果 NDIS 驅動程式必須建立裝置物件，它應該呼叫 NdisMRegisterDevice。 迷你埠和中繼驅動程序絕不會藉由呼叫 IoAttachDevice，嘗試在實體裝置物件上堆疊裝置物件。

使用 NdisMRegisterDevice 建立的裝置物件不是實體裝置物件，因此不會收到 隨插即用 或電源管理 IRP。 因此，NdisMRegisterDevice 的呼叫端必須省略 majorFunctions 所指向數位中 隨插即用 或電源管理處理程式的進入點。

請注意，如果開啟以 NdisMRegisterDevice 建立之裝置物件的句柄，就無法卸載建立裝置對象的驅動程式。 因此，使用者模式應用程式應該執行下列其中一項：

1. 當應用程式藉由呼叫 RegisterDeviceNotification 函式來註冊基礎裝置上的裝置事件通知時，請指定DBT_DEVTYP_HANDLE類型通知篩選器。 (如需 RegisterDeviceNotification 函式的詳細資訊，請參閱 Microsoft Windows SDK 檔案。) 如果應用程式後續收到裝置的DBT_DEVICEQUERYREMOVE事件，應用程式應該關閉開啟的句柄。

2. 當應用程式藉由呼叫 RegisterDeviceNotification 函式來註冊基礎裝置上的裝置事件通知時，請指定DBT_DEVTYP_DEVICEINTERFACE類型通知篩選，並GUID_NDIS_LAN_CLASS做為介面類別 GUID。 如果應用程式後續收到句柄所對應之裝置介面的DBT_DEVICEREMOVECOMPLETE事件，應用程式應該關閉開啟的句柄。

如果驅動程式對 NdisMRegisterDevice 的呼叫失敗，驅動程式可以繼續載入，視獨立裝置對象對驅動程式的作業有多重要而定。

• 目標平臺： 通用
• 版本：Windows Vista 中不支援 NDIS 6.0 驅動程式。 請改用 NdisRegisterDeviceEx。 Windows Vista 和 Windows XP 中支援 NDIS 5.1 驅動程式。

規格需求

需求	值
標頭	ndis.h (包含 Ndis.h)
程式庫	Ndis.lib
IRQL	PASSIVE_LEVEL

另請參閱

• NDIS 迷你埠驅動程式的 DriverEntry
• IoAttachDevice
• IoCreateDevice
• IoCreateSymbolicLink
• NdisMDeregisterDevice
• NdisMInitializeWrapper
• NdisRegisterDeviceEx
• UNICODE_STRING