SetupDiGetCustomDevicePropertyA-Funktion (setupapi.h)

Artikel
11/20/2024

Die SetupDiGetCustomDeviceProperty Funktion ruft eine angegebene benutzerdefinierte Geräteeigenschaft aus der Registrierung ab.

Syntax

WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            PCSTR            CustomPropertyName,
  [in]            DWORD            Flags,
  [out, optional] PDWORD           PropertyRegDataType,
  [out]           PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize
);

Parameter

[in] DeviceInfoSet

Ein Handle für den Geräteinformationssatz, das ein Geräteinformationselement enthält, das das Gerät darstellt, für das eine benutzerdefinierte Geräteeigenschaft abgerufen werden soll.

[in] DeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA Struktur, die das Geräteinformationselement in DeviceInfoSet-angibt.

[in] CustomPropertyName

Ein Registrierungswertname, der eine benutzerdefinierte Eigenschaft darstellt.

[in] Flags

Ein Flagwert, der angibt, wie die angeforderten Informationen zurückgegeben werden sollen. Die Kennzeichnung kann null oder eine der folgenden Werte sein:

DICUSTOMDEVPROP_MERGE_MULTISZ

Wenn festgelegt, ruft die Funktion sowohl geräteinstanzspezifische Eigenschaftswerte als auch Hardware-ID-spezifische Eigenschaftswerte ab, verkettet als REG_MULTI_SZ-typierte Zeichenfolge. (Weitere Informationen finden Sie im Abschnitt Anmerkungen auf dieser Referenzseite.)

[out, optional] PropertyRegDataType

Ein Zeiger auf eine Variable vom Typ DWORD, die den Datentyp der abgerufenen Eigenschaft empfängt. Der Datentyp wird als eine der REG_-Präfix-Konstanten angegeben, die Registrierungsdatentypen darstellen. Dieser Parameter ist optional und kann NULL-werden.

[out] PropertyBuffer

Ein Zeiger auf einen Puffer, der angeforderte Eigenschafteninformationen empfängt.

[in] PropertyBufferSize

Die Größe des PropertyBuffer- Puffers in Byte.

[out, optional] RequiredSize

Ein Zeiger auf eine Variable vom Typ DWORD, die die Puffergröße in Bytes empfängt, die zum Empfangen der angeforderten Informationen erforderlich ist. Dieser Parameter ist optional und kann NULL-werden. Wenn dieser Parameter angegeben ist, gibt SetupDiGetCustomDeviceProperty die erforderliche Größe zurück, unabhängig davon, ob der PropertyBuffer Puffer groß genug ist, um die angeforderten Informationen zu empfangen.

Rückgabewert

Wenn der Vorgang erfolgreich ist, gibt SetupDiGetCustomDevicePropertyTRUEzurück. Andernfalls gibt die Funktion FALSE- zurück, und der protokollierte Fehler kann mit einem Aufruf von GetLastErrorabgerufen werden. Wenn der PropertyBuffer- Puffer nicht groß genug ist, um die angeforderten Informationen zu erhalten, gibt SetupDiGetCustomDevicePropertyFALSE- zurück und ein anschließender Aufruf von GetLastError gibt ERROR_INSUFFICIENT_BUFFER zurück.

Bemerkungen

SetupDiGetCustomDeviceProperty ruft Geräteeigenschaften ab, die einer einzelnen Geräteinstanz oder allen Geräten zugeordnet sind, die einer bestimmten Hardware-ID entsprechen. (Informationen zu Hardware-IDs finden Sie unter Geräteidentifikationszeichenfolgen).

Anbieter können Eigenschaften für eine Geräteinstanz mithilfe INF-AddReg-Direktiven in INF DDInstall.HW-Abschnitten festlegen und den HKR Registrierungsstamm angeben.

Nur das System kann Eigenschaften für Hardware-IDs festlegen. Das System stellt eine "Icon"-Eigenschaft für einige Hardware-IDs bereit.

Die Funktion überprüft zunächst, ob die angegebene Eigenschaft für die angegebene Geräteinstanz vorhanden ist. Wenn ja, wird der Wert der Eigenschaft zurückgegeben. Andernfalls überprüft die Funktion, ob die Eigenschaft für alle Geräte vorhanden ist, die der Hardware-ID der angegebenen Geräteinstanz entsprechen. Wenn ja, wird der Wert der Eigenschaft zurückgegeben. Wenn DICUSTOMDEVPROP_MERGE_MULTISZ in Flagsfestgelegt ist, gibt die Funktion die Eigenschaftswerte zurück, die sowohl der Geräteinstanz als auch der Hardware-ID zugeordnet sind, sofern beide vorhanden sind.

Anmerkung

Der header setupapi.h definiert SetupDiGetCustomDeviceProperty als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Verfügbar in Windows XP und höheren Versionen von Windows.
Zielplattform-	Desktop
Header-	setupapi.h (include Setupapi.h)
Library	Setupapi.lib
DLL-	Setupapi.dll