IoEnumerateDeviceObjectList 函式 (ntifs.h)

發行項
03/01/2024

IoEnumerateDeviceObjectList 例程會列舉驅動程式的裝置物件清單。

語法

NTSTATUS IoEnumerateDeviceObjectList(
  [in]  PDRIVER_OBJECT DriverObject,
  [out] PDEVICE_OBJECT *DeviceObjectList,
  [in]  ULONG          DeviceObjectListSize,
  [out] PULONG         ActualNumberDeviceObjects
);

參數

[in] DriverObject

驅動程式物件的指標。

[out] DeviceObjectList

接收裝置物件指標的呼叫端配置陣列指標。此陣列必須從非分頁集區配置。此參數可以是 NULL。請參閱＜備註＞。

[in] DeviceObjectListSize

DeviceObjectList 陣列的大小，以位元組為單位。這個參數可以是零。請參閱＜備註＞。

[out] ActualNumberDeviceObjects

在驅動程式物件的裝置物件清單中找到的實際裝置物件數目。請注意，如果 DeviceObjectList 上的陣列太小，則複製到數位的裝置物件指標數目將會小於 ActualNumberDeviceObjects。

傳回值

IoEnumerateDeviceObjectList 會傳回 NTSTATUS 程序代碼，例如下列其中一個值：

傳回碼	Description
STATUS_SUCCESS	IoEnumerateDeviceObjectList 的呼叫已順利完成。
STATUS_BUFFER_TOO_SMALL	DeviceObjectList 上的陣列太小，無法保存整個裝置物件清單。在此情況下， IoEnumerateDeviceObjectList 會盡可能將許多裝置物件指標複製到陣列中。

備註

檔案系統篩選驅動程式會呼叫 IoEnumerateDeviceObjectList 來列舉：

其所建立的裝置物件。這通常是在驅動程序準備卸除時完成。請注意，無法安全地從執行中的系統卸除篩選驅動程式。如需詳細資訊，請參閱 ZwUnloadDriver。
基底文件系統所建立的裝置物件，因此篩選條件知道其可連結的磁碟區數目。

IoEnumerateDeviceObjectList 會傳回篩選驅動程式所建立的所有裝置物件。這包括 (CDOs) 的控制裝置物件，以及 (VDO) 的磁碟區裝置物件。這兩種類型的裝置物件可以透過慣例來區分，因為 CDO 是命名的，而 VDO 則不是。

在後者的情況下，篩選驅動程式通常會呼叫 IoEnumerateDeviceObjectList 兩次：一次可取得清單中的裝置物件數目，一次可取得裝置物件清單本身。在第一次呼叫中，呼叫端應該將 DeviceObjectList 參數設定為 NULL，並將 DeviceObjectListSize 設定為零。第二次呼叫時， DeviceObjectList 應該包含適當大小的指標陣列的指標，而 DeviceObjectListSize 應該包含該陣列的大小，以位元組為單位。

IoEnumerateDeviceObjectList 會遞增 DeviceObjectList 所指向清單中每個裝置對象的參考計數。因此，每次成功呼叫 IoEnumerateDeviceObjectList 時，都必須比對清單中每個裝置對象的後續對 ObDereferenceObject 呼叫。無法這麼做可防止系統因為未處理的參考計數而釋放或刪除這些裝置物件。

規格需求

需求	值
最低支援的用戶端	Windows 2000 SP4 更新匯總;Windowsxp
目標平台	Universal
標頭	ntifs.h (包含 Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL