SetupDiGetCustomDevicePropertyW-Funktion (setupapi.h)
Die SetupDiGetCustomDeviceProperty Funktion ruft eine angegebene benutzerdefinierte Geräteeigenschaft aus der Registrierung ab.
Syntax
WINSETUPAPI BOOL SetupDiGetCustomDevicePropertyW(
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in] PCWSTR 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 |
Siehe auch
SetupDiGetClassRegistryProperty
SetupDiGetDeviceRegistryProperty