SetupDiGetDeviceInterfacePropertyW-Funktion (setupapi.h)

Artikel
08/26/2023

Die SetupDiGetDeviceInterfaceProperty-Funktion ruft eine Geräteeigenschaft ab, die für eine Geräteschnittstelle festgelegt ist.

Syntax

WINSETUPAPI BOOL SetupDiGetDeviceInterfacePropertyW(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  [in]            const DEVPROPKEY          *PropertyKey,
  [out]           DEVPROPTYPE               *PropertyType,
  [out]           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äteschnittstelle enthält, für die eine Geräteschnittstelleneigenschaft abgerufen werden soll.

[in] DeviceInterfaceData

Ein Zeiger auf eine SP_DEVICE_INTERFACE_DATA Struktur, die die Geräteschnittstelle darstellt, für die eine Geräteschnittstelleneigenschaft abgerufen werden soll.

[in] PropertyKey

Ein Zeiger auf eine DEVPROPKEY-Struktur , die den Geräteschnittstelleneigenschaftsschlüssel der abzurufenden Geräteschnittstelleneigenschaft darstellt.

[out] PropertyType

Ein Zeiger auf eine DEVPROPTYPE-typisierte Variable, die den Eigenschaftsdatentypbezeichner der angeforderten Geräteschnittstelleneigenschaft empfängt. Der Eigenschaftsdatentypbezeichner ist ein bitweiser OR zwischen einem Basisdatentypbezeichner und, wenn der Basisdatentyp geändert wird, einem Property-data-type-Modifizierer.

[out] PropertyBuffer

Ein Zeiger auf einen Puffer, der die angeforderte Geräteschnittstelleneigenschaft empfängt. SetupDiGetDeviceInterfaceProperty 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 ist, gibt SetupDiGetDeviceInterfaceProperty 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 der Geräteschnittstelleneigenschaft 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

SetupDiGetDeviceInterfaceProperty 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. Andere Fehlercodes können von den Funktionen des Geräteinstallationsprogramms festgelegt werden, die von dieser API aufgerufen werden.

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 die von DeviceInterfaceData angegebene Geräteschnittstelle 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 PropertyBufferSize nicht 0 ist.
ERROR_NO_SUCH_DEVICE_INTERFACE	Die von DeviceInterfaceData angegebene Geräteschnittstelle ist nicht vorhanden.
ERROR_INSUFFICIENT_BUFFER	Der PropertyBuffer-Puffer ist nicht groß genug, um den 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

SetupDiGetDeviceInterfaceProperty ist Teil des einheitlichen Geräteeigenschaftenmodells.

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

Ein Aufrufer von SetupDiGetDeviceInterfaceProperty muss Mitglied der Gruppe Administratoren sein, um eine Geräteschnittstelleneigenschaft festzulegen.

Um die Geräteeigenschaftenschlüssel abzurufen, die die Geräteeigenschaften darstellen, die für eine Geräteschnittstelle festgelegt sind, rufen Sie SetupDiGetDeviceInterfacePropertyKeys auf.

Um eine Geräteschnittstelleneigenschaft festzulegen, rufen Sie SetupDiSetDeviceInterfaceProperty auf.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und späteren Windows-Versionen.
Zielplattform	DesktopFür universal rufen Sie CM_Get_Device_Interface_Property auf
Kopfzeile	setupapi.h (einschließlich Setupapi.h)
Bibliothek	Setupapi.lib

Weitere Informationen

SetupDiGetDeviceInterfacePropertyKeys

SetupDiSetDeviceInterfaceProperty