IoGetDeviceProperty-Funktion (wdm.h)
Die IoGetDeviceProperty-Routine ruft Informationen zu einem Gerät ab, z. B. Konfigurationsinformationen und den Namen des PDO.
Syntax
NTSTATUS IoGetDeviceProperty(
[in] PDEVICE_OBJECT DeviceObject,
[in] DEVICE_REGISTRY_PROPERTY DeviceProperty,
[in] ULONG BufferLength,
[out, optional] PVOID PropertyBuffer,
[out] PULONG ResultLength
);
Parameter
[in] DeviceObject
Zeiger auf das Objekt des physischen Geräts (PDO) für das abgefragte Gerät.
[in] DeviceProperty
Gibt die angeforderte Geräteeigenschaft an. Muss einer der folgenden DEVICE_REGISTRY_PROPERTY-Enumerationswerte sein:
DevicePropertyAddress
Fordert die Adresse des Geräts im Bus an. PropertyBuffer zeigt auf eine ULONG.
Die Interpretation dieser Adresse ist busspezifisch. Der Aufrufer dieser Routine sollte die Routine erneut aufrufen, um devicePropertyBusTypeGuid oder möglicherweise devicePropertyLegacyBusType anzufordern, damit er die Adresse interpretieren kann. Der Adresswert 0xFFFFFFFF gibt an, dass der zugrunde liegende Bustreiber keine Busadresse für das Gerät angegeben hat.
In der folgenden Liste werden die Informationen beschrieben, die bestimmte Bustreiber im PropertyBuffer für ihre untergeordneten Geräte speichern:
| Bus | BESCHREIBUNG |
|---|---|
| 1394 | Gibt keine Adresse an, da die Adressen flüchtig sind. Der Standardwert ist 0xFFFFFFFF. |
| EISA | Slotnummer (0-F). |
| IDE | Bei einem IDE-Gerät enthält die Adresse die Ziel-ID und die LUN. Für einen IDE-Kanal ist die Adresse null oder 1 (0 = primärer Kanal und 1 = sekundärer Kanal). |
| Isapnp | Gibt keine Adresse an. Der Standardwert ist 0xFFFFFFFF. |
| PC-Karte (PCMCIA) | Die Socketnummer (in der Regel 0x00 oder 0x40). |
| PCI | Die Gerätenummer im hohen Wort und die Funktionsnummer im unteren Wort. |
| SCSI | Die Ziel-ID. |
| USB | Die Portnummer. |
DevicePropertyBootConfiguration
Fordert die Hardwareressourcen an, die dem Gerät von der Firmware in unformatierter Form zugewiesen sind. PropertyBuffer zeigt auf eine CM_RESOURCE_LIST-Struktur .
DevicePropertyBootConfigurationTranslated
Die Hardwareressourcen, die dem Gerät von der Firmware in übersetzter Form zugewiesen werden. PropertyBuffer zeigt auf eine CM_RESOURCE_LIST-Struktur .
DevicePropertyBusNumber
Fordert die Legacybusnummer des Busses an, mit dem das Gerät verbunden ist. PropertyBuffer zeigt auf eine ULONG.
DevicePropertyBusTypeGuid
Fordert die GUID für den Bus an, mit dem das Gerät verbunden ist. Die systemdefinierten Bustyp-GUIDs sind in der Wdmguid.h-Headerdatei aufgeführt. PropertyBuffer zeigt auf eine GUID, bei der es sich um eine 16-Byte-Struktur handelt, die die GUID in binärer Form enthält.
DevicePropertyClassGuid
Fordert die GUID für die Setupklasse des Geräts an. PropertyBuffer zeigt auf ein NULL-beendetes Array von WCHAR. Diese Routine gibt die GUID wie folgt in einem Zeichenfolgenformat zurück, wobei jedes "c" ein hexadezimales Zeichen darstellt: {cccccc-cccc-cccc-cccccccccccc}
DevicePropertyClassName
Fordert den Namen der Setupklasse des Geräts im Textformat an. PropertyBuffer zeigt auf eine MIT NULL beendete WCHAR-Zeichenfolge.
DevicePropertyCompatibleIDs
Fordert die vom Gerät gemeldeten kompatiblen IDs an. PropertyBuffer zeigt auf einen REG_MULTI_SZ Wert.
DevicePropertyDeviceDescription
Fordert eine Zeichenfolge an, die das Gerät beschreibt, z. B. "Microsoft PS/2 Port Mouse", die in der Regel vom Hersteller definiert wird. PropertyBuffer zeigt auf eine MIT NULL beendete WCHAR-Zeichenfolge.
DevicePropertyDriverKeyName
Fordert den Namen des treiberspezifischen Registrierungsschlüssels an. PropertyBuffer zeigt auf eine MIT NULL beendete WCHAR-Zeichenfolge.
DevicePropertyEnumeratorName
Fordert den Namen des Enumerators für das Gerät an, z. B. "PCI" oder "root". PropertyBuffer zeigt auf eine MIT NULL beendete WCHAR-Zeichenfolge.
DevicePropertyFriendlyName
Fordert eine Zeichenfolge an, die verwendet werden kann, um zwischen zwei ähnlichen Geräten zu unterscheiden, die in der Regel vom Klasseninstallationsprogramm definiert werden. PropertyBuffer zeigt auf eine MIT NULL beendete WCHAR-Zeichenfolge.
DevicePropertyHardwareID
Fordert die vom Gerät bereitgestellten Hardware-IDs an, die das Gerät identifizieren. PropertyBuffer zeigt auf einen REG_MULTI_SZ Wert.
DevicePropertyInstallState
Fordert den Installationsstatus des Geräts an. Der Installationszustand wird als DEVICE_INSTALL_STATE-Enumerationswert zurückgegeben.
DevicePropertyLegacyBusType
Fordert den Bustyp an, z. B. PCIBus oder PCMCIABus. PropertyBuffer zeigt auf einen INTERFACE_TYPE Enumerationswert.
DevicePropertyLocationInformation
Fordert Informationen zum Standort des Geräts im Bus an; die Interpretation dieser Informationen ist busspezifisch. PropertyBuffer zeigt auf eine MIT NULL beendete WCHAR-Zeichenfolge.
DevicePropertyManufacturer
Fordert eine Zeichenfolge an, die den Hersteller des Geräts identifiziert. PropertyBuffer zeigt auf eine MIT NULL beendete WCHAR-Zeichenfolge.
DevicePropertyPhysicalDeviceObjectName
Fordert den Namen des PDO für dieses Gerät an. PropertyBuffer zeigt auf eine MIT NULL beendete WCHAR-Zeichenfolge.
DevicePropertyRemovalPolicy
Fordert die aktuelle Entfernungsrichtlinie des Geräts an. Das Betriebssystem verwendet diesen Wert als Hinweis, um zu bestimmen, wie das Gerät normalerweise entfernt wird. Der PropertyBuffer-Parameter verweist auf einen DEVICE_REMOVAL_POLICY Enumerationswert.
DevicePropertyUINumber
Fordert eine Nummer an, die dem Gerät zugeordnet ist und auf der Benutzeroberfläche angezeigt werden kann. PropertyBuffer zeigt auf einen ULONG-Wert.
Diese Nummer ist in der Regel eine vom Benutzer wahrgenommene Slotnummer, z. B. eine Zahl, die neben dem Slot auf der Platine gedruckt wird, oder eine andere Nummer, die das Auffinden des physischen Geräts für den Benutzer erleichtert. Wenn sich das Gerät auf einem Bus befindet, der keine Konvention für Benutzeroberflächennummern aufweist, oder wenn der Bustreiber für das Gerät die Ui-Nummer nicht bestimmen kann, wird dieser Wert 0xFFFFFFFF.
[in] BufferLength
Gibt die Größe des vom Aufrufer bereitgestellten PropertyBuffer in Bytes an.
[out, optional] PropertyBuffer
Zeiger auf einen vom Aufrufer bereitgestellten Puffer, um die Eigenschafteninformationen zu empfangen. Der Puffer kann aus ausgelagertem Arbeitsspeicher zugeordnet werden. Der Typ des Puffers wird durch deviceProperty bestimmt (siehe oben).
[out] ResultLength
Zeiger auf eine ULONG, um die Größe der Eigenschafteninformationen zu erhalten, die bei PropertyBuffer zurückgegeben werden. Wenn IoGetDeviceProperty STATUS_BUFFER_TOO_SMALL zurückgibt, wird dieser Parameter auf die erforderliche Pufferlänge festgelegt.
Rückgabewert
IoGetDeviceProperty gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich war. Mögliche Fehlerrückgabewerte sind:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_BUFFER_TOO_SMALL | Der Puffer bei PropertyBuffer war zu klein. ResultLength zeigt auf die erforderliche Pufferlänge. |
| STATUS_INVALID_PARAMETER_2 | Die angegebene DeviceProperty ist keine der Eigenschaften, die von dieser Routine behandelt werden. |
| STATUS_INVALID_DEVICE_REQUEST | Gibt möglicherweise an, dass das angegebene DeviceObject kein gültiger PDO-Zeiger war. |
Hinweise
IoGetDeviceProperty ruft Gerätesetupinformationen aus der Registrierung ab. Verwenden Sie diese Routine, anstatt direkt auf die Registrierung zuzugreifen, um einen Treiber vor Plattformunterschieden und möglichen Änderungen in der Registrierungsstruktur zu isolieren.
Bei vielen DeviceProperty-Anforderungen kann es zwei oder mehr Aufrufe von IoGetDeviceProperty erfordern, um den erforderlichen BufferLength zu ermitteln. Für den ersten Aufruf sollte ein Best-Guess-Wert verwendet werden. Wenn der status STATUS_BUFFER_TOO_SMALL ist, sollte der Treiber seinen aktuellen Puffer freigeben, einen Puffer der in ResultLength zurückgegebenen Größe zuordnen und IoGetDeviceProperty erneut aufrufen. Da einige der Setupeigenschaften dynamisch sind, kann sich die Datengröße zwischen der Rückgabe der erforderlichen Größe ändern und der Treiber diese Routine erneut aufruft. Daher sollten Treiber IoGetDeviceProperty in einer Schleife aufrufen, die ausgeführt wird, bis die Rückgabe status nicht STATUS_BUFFER_TOO_SMALL wird.
Funktionstreiber, die Geräte auf einem Legacy-Bus und einem PnP-Bus unterstützen, können die Eigenschaften DevicePropertyBusNumber, DevicePropertyBusTypeGuid und DevicePropertyLegacyBusType verwenden, um zwischen den Bussen zu unterscheiden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar ab Windows 2000. |
| Zielplattform | Universell |
| Header | wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL |
| DDI-Complianceregeln | HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm) |