(wdm.h) IoGetDeviceProperty 函式

發行項
02/29/2024

IoGetDeviceProperty 例程會擷取裝置的相關信息，例如組態資訊和其 PDO 的名稱。

語法

NTSTATUS IoGetDeviceProperty(
  [in]            PDEVICE_OBJECT           DeviceObject,
  [in]            DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]            ULONG                    BufferLength,
  [out, optional] PVOID                    PropertyBuffer,
  [out]           PULONG                   ResultLength
);

參數

[in] DeviceObject

要查詢之裝置的實體裝置物件指標 (PDO) 。

[in] DeviceProperty

指定要要求的裝置屬性。必須是下列其中一個 DEVICE_REGISTRY_PROPERTY 列舉值：

DevicePropertyAddress

要求總線上的裝置位址。 PropertyBuffer 指向 ULONG。

此位址的解譯是總線特定的。此例程的呼叫端應該再次呼叫例程來要求 DevicePropertyBusTypeGuid，或可能是 DevicePropertyLegacyBusType，以便解譯位址。 0xFFFFFFFF位址值表示基礎總線驅動程式未提供裝置的總線位址。

下列清單描述其子裝置 之 PropertyBuffer 中特定總線驅動程式儲存的資訊：

匯流排	Description
1394	不會提供地址，因為位址是變動的。默認為 0xFFFFFFFF。
EISA	插槽號碼 (0-F) 。
IDE	若為 IDE 裝置，位址會包含目標標識碼和 LUN。若為 IDE 通道，位址為零或一個 (0 = 主要通道，而 1 = 次要通道) 。
ISApnp	不提供位址。默認為 0xFFFFFFFF。
PC Card (PCMCIA)	套接字號碼 (通常會0x00或0x40) 。
PCI	高字的裝置編號，以及低字的函式編號。
SCSI	目標標識碼。
USB	連接埠號碼。

DevicePropertyBootConfiguration

以原始形式要求韌體指派給裝置的硬體資源。 PropertyBuffer 指向 CM_RESOURCE_LIST 結構。

DevicePropertyBootConfigurationTranslated

韌體指派給裝置的硬體資源，格式為已轉譯。 PropertyBuffer 指向 CM_RESOURCE_LIST 結構。

DevicePropertyBusNumber

要求裝置所連線的舊版總線號碼。 PropertyBuffer 指向 ULONG。

DevicePropertyBusTypeGuid

要求裝置所連線總線的 GUID。系統定義的總線類型 GUID 會列在 Wdmguid.h 頭檔中。 PropertyBuffer 指向 GUID，這是包含二進位格式 GUID 的 16 位元組結構。

DevicePropertyClassGuid

要求裝置設定類別的 GUID。 PropertyBuffer 指向 WCHAR 的 NULL 終止數位。此例程會以字串格式傳回 GUID，其中每個 “c” 代表十六進位字元： {cccccccc-cccc-cccc-cc}

DevicePropertyClassName

以文字格式要求裝置的安裝類別名稱。 PropertyBuffer 指向 NULL 終止的 WCHAR 字串。

DevicePropertyCompatibleIDs

要求裝置所報告的相容標識碼。 PropertyBuffer 指向REG_MULTI_SZ值。

DevicePropertyDeviceDescription

要求描述裝置的字串，例如「Microsoft PS/2 埠滑鼠」，通常是由製造商所定義。 PropertyBuffer 指向 NULL 終止的 WCHAR 字串。

DevicePropertyDriverKeyName

要求驅動程式特定登錄機碼的名稱。 PropertyBuffer 指向 NULL 終止的 WCHAR 字串。

DevicePropertyEnumeratorName

要求裝置的列舉值名稱，例如「PCI」或「root」。 PropertyBuffer 指向 NULL 終止的 WCHAR 字串。

DevicePropertyFriendlyName

要求可用來區別兩個類似裝置的字串，通常是由類別安裝程式所定義。 PropertyBuffer 指向 NULL 終止的 WCHAR 字串。

DevicePropertyHardwareID

要求裝置提供的硬體識別碼，以識別裝置。 PropertyBuffer 指向REG_MULTI_SZ值。

DevicePropertyInstallState

要求裝置的安裝狀態。安裝狀態會以 DEVICE_INSTALL_STATE 列舉值傳回。

DevicePropertyLegacyBusType

要求總線類型，例如PCIBus或PCMCIABus。 PropertyBuffer 指向 INTERFACE_TYPE 列舉值。

DevicePropertyLocationInformation

要求有關裝置在公交車上位置的資訊;此資訊的解譯是總線特定的。 PropertyBuffer 指向 NULL 終止的 WCHAR 字串。

DevicePropertyManufacturer

要求識別裝置製造商的字串。 PropertyBuffer 指向 NULL 終止的 WCHAR 字串。

DevicePropertyPhysicalDeviceObjectName

要求此裝置的 PDO 名稱。 PropertyBuffer 指向 NULL 終止的 WCHAR 字串。

DevicePropertyRemovalPolicy

要求裝置目前的移除原則。操作系統會使用此值作為提示，以判斷裝置一般移除的方式。 PropertyBuffer 參數會指向DEVICE_REMOVAL_POLICY列舉值。

DevicePropertyUINumber

要求與可在使用者介面中顯示的裝置相關聯的數位。 PropertyBuffer 指向 ULONG 值。

此數位通常是使用者感知的插槽編號，例如在面板上的位置旁邊列印的數位，或一些其他數位，可讓使用者更輕鬆地尋找實體裝置。如果裝置位於沒有UI號碼慣例的總線上，或裝置的總線驅動程式無法判斷UI號碼，則此值會0xFFFFFFFF。

[in] BufferLength

指定呼叫端提供 PropertyBuffer 的大小，以位元組為單位。

[out, optional] PropertyBuffer

呼叫端提供的緩衝區指標，以接收屬性資訊。緩衝區可以從可分頁記憶體配置。緩衝區的類型取決於 DeviceProperty (請參閱上述) 。

[out] ResultLength

ULONG 的指標，以接收 在 PropertyBuffer 傳回的屬性資訊大小。如果 IoGetDeviceProperty 傳回STATUS_BUFFER_TOO_SMALL，它會將此參數設定為必要的緩衝區長度。

傳回值

如果呼叫成功，IoGetDeviceProperty 會傳回STATUS_SUCCESS。可能的錯誤傳回值包括下列專案。

傳回碼	Description
STATUS_BUFFER_TOO_SMALL	PropertyBuffer 上的緩衝區太小。 ResultLength 指向所需的緩衝區長度。
STATUS_INVALID_PARAMETER_2	指定的 DeviceProperty 不是這個例程所處理的屬性之一。
STATUS_INVALID_DEVICE_REQUEST	可能表示指定的 DeviceObject 不是有效的 PDO 指標。

備註

IoGetDeviceProperty 會從登錄擷取裝置安裝資訊。使用此例程，而不是直接存取登錄，以隔離驅動程式與跨平台的差異，以及登錄結構中的可能變更。

對於許多 DeviceProperty 要求，可能需要兩或多個呼叫 IoGetDeviceProperty 來判斷所需的 BufferLength。第一個呼叫應該使用最佳猜測值。如果傳回狀態STATUS_BUFFER_TOO_SMALL，驅動程式應該釋放其目前緩衝區、配置 ResultLength 中所傳回大小的緩衝區，然後再次呼叫 IoGetDeviceProperty 。由於部分安裝屬性是動態的，因此數據大小可以在傳回所需大小的時間之間變更，而驅動程式會再次呼叫此例程。因此，驅動程式應該在迴圈內呼叫 IoGetDeviceProperty ，直到傳回狀態未STATUS_BUFFER_TOO_SMALL為止。

支援舊版總線和 PnP 總線上裝置的函式驅動程式可以使用 DevicePropertyBusNumber、 DevicePropertyBusTypeGuid 和 DevicePropertyLegacyBusType 屬性來區分總線。

規格需求

需求	值
最低支援的用戶端	從 Windows 2000 開始提供。
目標平台	Universal
標頭	wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
程式庫	NtosKrnl.lib
Dll	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 合規性規則	HwStorPortProhibitedDDIs (storport) 、 PowerIrpDDis (wdm)