IoGetDeviceObjectPointer 函式 (wdm.h)
IoGetDeviceObjectPointer 例程會傳回具名裝置物件堆疊中頂端物件的指標,以及對應檔案物件的指標,如果可以授與對物件的要求存取權。
語法
NTSTATUS IoGetDeviceObjectPointer(
[in] PUNICODE_STRING ObjectName,
[in] ACCESS_MASK DesiredAccess,
[out] PFILE_OBJECT *FileObject,
[out] PDEVICE_OBJECT *DeviceObject
);
參數
[in] ObjectName
緩衝區的指標,其中包含裝置物件名稱的 Unicode 字串。
[in] DesiredAccess
指定代表所需存取權的 ACCESS_MASK 值。 通常 DesiredAccess 是FILE_READ_DATA。 不常指定FILE_WRITE_DATA或FILE_ALL_ACCESS訪問許可權。
[out] FileObject
如果呼叫成功,則代表對應裝置物件的檔案物件指標至使用者模式程序代碼。
[out] DeviceObject
如果呼叫成功,代表具名邏輯、虛擬或實體裝置的裝置物件的指標。
傳回值
IoGetDeviceObjectPointer 如果成功,就會傳回STATUS_SUCCESS。 可能的錯誤傳回值包括下列狀態代碼:
STATUS_OBJECT_TYPE_MISMATCH
STATUS_INVALID_PARAMETER
STATUS_PRIVILEGE_NOT_HELD
STATUS_INSUFFICIENT_RESOURCES
STATUS_OBJECT_NAME_INVALID
言論
IoGetDeviceObjectPointer 會建立呼叫端與下一個較低層級驅動程式之間的「連線」。 成功的呼叫端可以使用傳回的裝置物件指標來初始化自己的裝置物件。 它也可以用來做為自變數來 IoAttachDeviceToDeviceStack、IoCallDriver,以及為較低驅動程式建立 IRP 的任何例程。 傳回的指標是 IoCallDriver的必要自變數。
這個例程也會傳回對應檔案物件的指標。 卸除時,驅動程式可以將檔案物件取值做為間接取值裝置物件的方法。 若要這樣做,驅動程式會從其 Unload 例程呼叫 ObDereferenceObject,並傳遞 ioGetDeviceObjectPointer 所傳回的檔案對象指標。 無法在驅動程式的 Unload 例程中取值裝置對象,導致下一個較低的驅動程式無法卸除。 不過,在卸除程式之前關閉檔案對象的驅動程式必須在取值檔案物件之前,先在裝置物件上取出額外的參考。 否則,取值檔案物件可能會導致裝置物件的過早刪除。
若要取得文件系統驅動程式堆疊中最高層級驅動程式的指標,驅動程式必須確定已掛接文件系統;如果不是,此例程會周遊記憶體裝置堆疊。 為了確保文件系統掛接在儲存設備上,驅動程式必須在 DesiredAccess 參數中指定適當的存取掩碼,例如FILE_READ_DATA或FILE_WRITE_ATTRIBUTES。 指定FILE_READ_ATTRIBUTES不會使檔案系統掛接。
在成功呼叫此例程以將任何較高層級驅動程序鏈結至另一個驅動程序之後,較高層級的驅動程式必須將其裝置物件中的 StackSize 字段設定為下一個較低層級驅動程式的裝置物件加上一個。
IoGetDeviceObjectPointer 的呼叫端必須在 IRQL = PASSIVE_LEVEL執行。
要求
要求 | 價值 |
---|---|
最低支援的用戶端 | 從 Windows 2000 開始提供。 |
目標平臺 | 普遍 |
標頭 | wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h) |
連結庫 | NtosKrnl.lib |
DLL | NtosKrnl.exe |
IRQL | PASSIVE_LEVEL |
DDI 合規性規則 | HwStorPortProhibitedDIs(storport)、IrqlIoPassive5(wdm)、PowerIrpDDis(wdm) |