ioGetDeviceObjectPointer 函式 (wdm.h)

發行項
02/29/2024

如果可以授與要求的存取物件， 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 開始提供。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 IrqlIoPassive5 (wdm) 、 PowerIrpDDis (wdm)