SetupDiSetClassPropertyExW-Funktion (setupapi.h)
Die SetupDiSetClassPropertyEx-Funktion legt eine Geräteeigenschaft für eine Geräteeinrichtungsklasse oder eine Geräteschnittstellenklasse auf einem lokalen oder Remotecomputer fest.
Syntax
WINSETUPAPI BOOL SetupDiSetClassPropertyExW(
[in] const GUID *ClassGuid,
[in] const DEVPROPKEY *PropertyKey,
[in] DEVPROPTYPE PropertyType,
[in, optional] const PBYTE PropertyBuffer,
[in] DWORD PropertyBufferSize,
[in] DWORD Flags,
[in, optional] PCWSTR MachineName,
PVOID Reserved
);
Parameter
[in] ClassGuid
Ein Zeiger auf eine GUID, die die Geräteeinrichtungsklasse oder Geräteschnittstellenklasse identifiziert, für die eine Geräteeigenschaft festgelegt werden soll. Informationen zum Angeben des Klassentyps finden Sie im Flags-Parameter .
[in] PropertyKey
Ein Zeiger auf eine DEVPROPKEY-Struktur , die den Geräteeigenschaftenschlüssel der festzulegenden Geräteklasseneigenschaft darstellt.
[in] PropertyType
Ein DEVPROPTYPE-typisierter Wert, der den Bezeichner property-data-type für die Klasseneigenschaft darstellt. Weitere Informationen zum Bezeichner für Eigenschaftsdatentyp finden Sie weiter unten in diesem Thema im Abschnitt Hinweise .
[in, optional] PropertyBuffer
Ein Zeiger auf einen Puffer, der den Klasseneigenschaftswert enthält. Wenn entweder die Eigenschaft oder der Eigenschaftswert gelöscht wird, muss dieser Zeiger auf NULL festgelegt werden, und PropertyBufferSize muss auf 0 festgelegt werden. Weitere Informationen zu Eigenschaftenwertanforderungen finden Sie weiter unten in diesem Thema im Abschnitt Hinweise .
[in] PropertyBufferSize
Die Größe des PropertyBuffer-Puffers in Bytes. Die Größe des Eigenschaftspuffers muss mit dem Eigenschaftsdatentypbezeichner übereinstimmen, der von PropertyType bereitgestellt wird. Wenn PropertyBuffer auf NULL festgelegt ist, muss PropertyBufferSize auf 0 festgelegt werden.
[in] Flags
Einer der folgenden Werte, der angibt, ob es sich bei der Klasse um eine Geräteeinrichtungsklasse oder eine Geräteschnittstellenklasse handelt:
DICLASSPROP_INSTALLER
ClassGuid gibt eine Gerätesetupklasse an. Dieses Flag kann nicht mit DICLASSPROP_INTERFACE verwendet werden.
DICLASSPROP_INTERFACE
ClassGuid gibt eine Geräteschnittstellenklasse an. Dieses Flag kann nicht mit DICLASSPROP_INSTALLER verwendet werden.
[in, optional] MachineName
Ein Zeiger auf eine MIT NULL beendete Unicode-Zeichenfolge, die den UNC-Namen einschließlich des Präfixes "\" eines Computers enthält. Dieser Zeiger kann auf NULL festgelegt werden. Wenn der Zeiger NULL ist, legt SetupDiSetClassPropertyEx die Klasseneigenschaft für eine Klasse fest, die auf dem lokalen Computer installiert ist.
Achtung
Die Verwendung dieser Funktion für den Zugriff auf Remotecomputer wird ab Windows 8 und Windows Server 2012 nicht unterstützt, da diese Funktionalität entfernt wurde.
Reserved
Dieser Parameter muss auf NULL festgelegt werden.
Rückgabewert
SetupDiSetClassPropertyEx 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 |
|---|---|
|
Der Wert von Flags ist ungültig. |
|
Die von ClassGuid angegebene Geräteeinrichtungsklasse ist ungültig. Dieser Fehler kann nur auftreten, wenn das DICLASSPROP_INSTALLER-Flag angegeben ist. |
|
Die Referenzzeichenfolge der Geräteschnittstelle ist ungültig. Dieser Fehler kann nur auftreten, wenn das flag DICLASSPROP_INTERFACE angegeben ist. |
|
Der von PropertyKey bereitgestellte Eigenschaftenschlüssel ist ungültig. |
|
Ein nicht angegebener interner Datenwert war ungültig. Dieser Fehler kann protokolliert werden, wenn entweder der ClassGuid-Wert keine gültige GUID ist oder der Eigenschaftswert nicht mit dem von PropertyType angegebenen Eigenschaftstyp übereinstimmt. |
|
Ein Benutzerpuffer ist ungültig. Eine Möglichkeit besteht darin, dass PropertyBufferNULL und PropertyBufferSize nicht 0 ist. |
|
Der von MachineName angegebene Computername ist ungültig. |
|
Die von ClassGuid angegebene Geräteschnittstellenklasse ist nicht vorhanden. Dieser Fehler kann nur auftreten, wenn das flag DICLASSPROP_INTERFACE angegeben ist. |
|
Ein interner Datenpuffer, der an einen Systemaufruf übergeben wurde, war zu klein. |
|
Es war nicht genügend Systemspeicher verfügbar, um den Vorgang abzuschließen. |
|
Ein nicht angegebenes Element wurde nicht gefunden. Eine Möglichkeit besteht darin, dass die zu löschende Eigenschaft nicht vorhanden ist. |
|
Der Aufrufer verfügt nicht über Administratorrechte. |
Hinweise
SetupDiSetClassPropertyEx ist Teil des einheitlichen Geräteeigenschaftenmodells.
SetupAPI unterstützt nur eine Unicode-Version von SetupDiSetClassPropertyEx.
Ein Aufrufer von SetupDiSetClassPropertyEx muss Mitglied der Gruppe Administratoren sein, um eine Geräteschnittstelleneigenschaft festzulegen.
SetupDiSetClassPropertyEx erzwingt Anforderungen für den Bezeichner property-data-type und den Eigenschaftswert.
Rufen Sie SetupDiGetClassPropertyKeysEx auf, um die Geräteeigenschaften abzurufen, die für eine Geräteklasse auf einem Remotecomputer festgelegt sind.
Um eine Geräteklasseneigenschaft auf einem lokalen Computer abzurufen, rufen Sie SetupDiGetClassProperty auf, und um eine Geräteklasseneigenschaft auf einem Remotecomputer abzurufen, rufen Sie SetupDiGetClassPropertyEx auf.
Um eine Geräteklasseneigenschaft auf einem lokalen Computer festzulegen, rufen Sie SetupDiSetClassProperty auf.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar in Windows Vista und späteren Windows-Versionen. |
| Zielplattform | Desktop |
| Kopfzeile | setupapi.h (einschließlich Setupapi.h) |
| Bibliothek | Setupapi.lib |