SetupDiGetCustomDevicePropertyA-Funktion (setupapi.h)

Artikel
03/01/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 , der 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. Das Flag kann null oder eines der folgenden Sein:

DICUSTOMDEVPROP_MERGE_MULTISZ

Wenn festgelegt, ruft die Funktion sowohl Geräte- instance-spezifische Eigenschaftswerte als auch Hardware-ID-spezifische Eigenschaftswerte ab, die als REG_MULTI_SZ typisierte Zeichenfolge verkettet werden. (Weitere Informationen finden Sie im Abschnitt Hinweise 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äfixkonstanten angegeben, die Registrierungsdatentypen darstellen. Dieser Parameter ist optional und kann NULL sein.

[out] PropertyBuffer

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

[in] PropertyBufferSize

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

[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 sein. 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 SetupDiGetCustomDevicePropertyTRUE zurück. Andernfalls gibt die Funktion FALSE zurück, und der protokollierte Fehler kann mit einem Aufruf von GetLastError abgerufen werden. Wenn der PropertyBuffer-Puffer nicht groß genug ist, um die angeforderten Informationen zu empfangen, gibt SetupDiGetCustomDevicePropertyFALSE zurück, und ein späterer Aufruf von GetLastError gibt ERROR_INSUFFICIENT_BUFFER zurück.

Hinweise

SetupDiGetCustomDeviceProperty ruft Geräteeigenschaften ab, die einem einzelnen Gerät instance 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 ein Gerät instance festlegen, indem sie INF AddReg-Anweisungen in INF DDInstall.HW-Abschnitten verwenden 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 das angegebene Gerät instance vorhanden ist. In diesem Fall 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 des angegebenen Geräts instance entsprechen. In diesem Fall wird der Wert der Eigenschaft zurückgegeben. Wenn DICUSTOMDEVPROP_MERGE_MULTISZ in Flags festgelegt ist, gibt die Funktion die Eigenschaftenwerte zurück, die sowohl dem gerätebasierten instance als auch der Hardware-ID zugeordnet sind, sofern beide vorhanden sind.

Hinweis

Der setupapi.h-Header definiert SetupDiGetCustomDeviceProperty als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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
Unterstützte Mindestversion (Client)	Verfügbar in Windows XP und höheren Versionen von Windows.
Zielplattform	Desktop
Kopfzeile	setupapi.h (einschließlich Setupapi.h)
Bibliothek	Setupapi.lib
DLL	Setupapi.dll