(wdm.h) IoGetDeviceProperty 函式
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) |