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:

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:

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

Weitere Informationen

CM_RESOURCE_LIST

DEVICE_REMOVAL_POLICY

ExAllocatePoolWithTag

GUID

INTERFACE_TYPE

IO_RESOURCE_REQUIREMENTS_LIST