SetupDiGetDevicePropertyW-Funktion (setupapi.h)

  • Artikel

Die SetupDiGetDeviceProperty-Funktion ruft ein Gerät instance-Eigenschaft ab.

Syntax

WINSETUPAPI BOOL SetupDiGetDevicePropertyW(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            const DEVPROPKEY *PropertyKey,
  [out]           DEVPROPTYPE      *PropertyType,
  [out, optional] PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize,
  [in]            DWORD            Flags
);

Parameter

[in] DeviceInfoSet

Ein Handle für einen Geräteinformationssatz, der eine Geräte-instance enthält, für die ein Gerät instance Eigenschaft abgerufen werden soll.

[in] DeviceInfoData

Ein Zeiger auf die SP_DEVINFO_DATA Struktur, die das Gerät darstellt, instance für das ein Gerät instance Eigenschaft abgerufen werden soll.

[in] PropertyKey

Ein Zeiger auf eine DEVPROPKEY-Struktur, die den Geräteeigenschaftenschlüssel des angeforderten Geräts instance-Eigenschaft darstellt.

[out] PropertyType

Ein Zeiger auf eine DEVPROPTYPE-typisierte Variable, die den Eigenschaftsdatentypbezeichner des angeforderten Geräts instance-Eigenschaft empfängt, wobei der Eigenschaft-Datentypbezeichner der bitweise OR zwischen einem Basisdatentypbezeichner und, wenn der Basisdatentyp geändert wird, einem Eigenschaft-Datentyp-Modifizierer ist.

[out, optional] PropertyBuffer

Ein Zeiger auf einen Puffer, der das angeforderte Gerät instance-Eigenschaft empfängt. SetupDiGetDeviceProperty ruft die angeforderte Eigenschaft nur ab, wenn der Puffer groß genug ist, um alle Eigenschaftenwertdaten aufzunehmen. Der Zeiger kann NULL sein. Wenn der Zeiger auf NULL festgelegt ist und RequiredSize angegeben wird, gibt SetupDiGetDeviceProperty die Größe der Eigenschaft in Bytes in *RequiredSize zurück.

[in] PropertyBufferSize

Die Größe des PropertyBuffer-Puffers in Bytes. Wenn PropertyBuffer auf NULL festgelegt ist, muss PropertyBufferSize auf 0 festgelegt werden.

[out, optional] RequiredSize

Ein Zeiger auf eine DWORD-typisierte Variable, die die Größe des Geräts instance Eigenschaft in Bytes empfängt, wenn die Eigenschaft abgerufen wird, oder die erforderliche Puffergröße, wenn der Puffer nicht groß genug ist. Dieser Zeiger kann auf NULL festgelegt werden.

[in] Flags

Dieser Parameter muss auf 0 festgelegt werden.

Rückgabewert

SetupDiGetDeviceProperty gibt TRUE zurück, wenn es erfolgreich ist. Andernfalls wird FALSE zurückgegeben, und der protokollierte Fehler kann durch Aufrufen von GetLastError abgerufen werden.

Die folgende Tabelle enthält einige der häufigeren Fehlercodes, die diese Funktion möglicherweise protokolliert.

Rückgabecode Beschreibung
ERROR_INVALID_FLAGS
 Der Wert von Flags ist nicht 0.
ERROR_INVALID_HANDLE
 Der von DevInfoSet angegebene Geräteinformationssatz ist ungültig.
ERROR_INVALID_PARAMETER
 Ein bereitgestellter Parameter ist ungültig. Eine Möglichkeit besteht darin, dass das Geräteinformationselement ungültig ist.
ERROR_INVALID_REG_PROPERTY
 Der von PropertyKey bereitgestellte Eigenschaftenschlüssel ist ungültig.
ERROR_INVALID_DATA
 Ein nicht angegebener interner Datenwert war ungültig.
ERROR_INVALID_USER_BUFFER
 Ein Benutzerpuffer ist ungültig. Eine Möglichkeit besteht darin, dass PropertyBufferNULL und PropertBufferSize nicht 0 ist.
ERROR_NO_SUCH_DEVINST
 Das gerät instance, das von DevInfoData angegeben wird, ist nicht vorhanden.
ERROR_INSUFFICIENT_BUFFER
 Der PropertyBuffer-Puffer ist zu klein, um den angeforderten Eigenschaftswert aufzunehmen, oder ein interner Datenpuffer, der an einen Systemaufruf übergeben wurde, war zu klein.
ERROR_NOT_ENOUGH_MEMORY
 Es war nicht genügend Systemspeicher verfügbar, um den Vorgang abzuschließen.
ERROR_NOT_FOUND
 Die angeforderte Geräteeigenschaft ist nicht vorhanden.
ERROR_ACCESS_DENIED
 Der Aufrufer verfügt nicht über Administratorrechte.

Hinweise

SetupDiGetDeviceProperty ist Teil des einheitlichen Geräteeigenschaftenmodells.

SetupAPI unterstützt nur eine Unicode-Version von SetupDiGetDeviceProperty.

Rufen Sie SetupDiGetDevicePropertyKeys auf, um die Geräteeigenschaften abzurufen, die für ein Gerät instance festgelegt sind.

Um ein Gerät instance Eigenschaft festzulegen, rufen Sie SetupDiSetDeviceProperty auf.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Windows Vista und späteren Windows-Versionen.
Zielplattform Desktop Für universell rufen Sie CM_Get_DevNode_Property auf
Kopfzeile setupapi.h (einschließlich SetupAPI.h)
Bibliothek SetupAPI.lib
DLL SetupAPI.dll
APIs ext-ms-win-setupapi-classinstallers-l1-1-0 (eingeführt in Windows 8)

Weitere Informationen

SetupDiGetDevicePropertyKeys

SetupDiSetDeviceProperty