SetupDiGetClassPropertyExW-Funktion (setupapi.h)

Artikel
08/26/2023

Die SetupDiGetClassPropertyEx-Funktion ruft eine Klasseneigenschaft für eine Gerätesetupklasse oder eine Geräteschnittstellenklasse auf einem lokalen oder Remotecomputer ab.

Syntax

WINSETUPAPI BOOL SetupDiGetClassPropertyExW(
  [in]            const GUID       *ClassGuid,
  [in]            const DEVPROPKEY *PropertyKey,
  [out]           DEVPROPTYPE      *PropertyType,
  [out, optional] PBYTE            PropertyBuffer,
  [in]            DWORD            PropertyBufferSize,
  [out, optional] PDWORD           RequiredSize,
  [in]            DWORD            Flags,
  [in, optional]  PCWSTR           MachineName,
                  PVOID            Reserved
);

Parameter

[in] ClassGuid

Ein Zeiger auf eine GUID, die die Gerätesetupklasse oder Geräteschnittstellenklasse identifiziert, für die eine Geräteeigenschaft für die Geräteklasse abgerufen werden soll. Informationen zum Angeben des Klassentyps finden Sie im Flags-Parameter .

[in] PropertyKey

Ein Zeiger auf eine DEVPROPKEY-Struktur , die den Geräteeigenschaftsschlüssel der angeforderten Geräteklasseneigenschaft darstellt.

[out] PropertyType

Ein Zeiger auf eine VARIABLE vom Typ DEVPROPTYPE, die den Property-Data-Type-Bezeichner der angeforderten Geräteklasseneigenschaft empfängt, wobei der Property-Data-Type-Bezeichner der bitweise OR zwischen einem Basisdatentypbezeichner und, wenn der Basisdatentyp geändert wird, einem Property-Data-Type-Modifizierer ist.

[out, optional] PropertyBuffer

Ein Zeiger auf einen Puffer, der die angeforderte Geräteklasseneigenschaft empfängt. SetupDiGetClassPropertyEx ruft den angeforderten Eigenschaftswert nur ab, wenn der Puffer groß genug ist, um alle Eigenschaftenwertdaten zu enthalten. Der Zeiger kann NULL sein. Wenn der Zeiger auf NULL festgelegt ist und RequiredSize angegeben wird, gibt SetupDiGetClassPropertyEx die Größe der Geräteklasseneigenschaft in Byte in *RequiredSize zurück.

[in] PropertyBufferSize

Die Größe des PropertyBuffer-Puffers in Bytes. Wenn PropertyBuffer auf NULL festgelegt ist, muss PropertyBufferSize auf Null festgelegt werden.

[out, optional] RequiredSize

Ein Zeiger auf eine Variable vom Typ DWORD, die entweder die Größe der Geräteklasseneigenschaft 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

Einer der folgenden Werte, der angibt, ob die Klasse eine Gerätesetupklasse oder eine Geräteschnittstellenklasse ist:

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 NULL-beendete Zeichenfolge, die den UNC-Namen einschließlich des Präfixes "\" eines Computers enthält. Der Zeiger kann auf NULL festgelegt werden. Wenn MachineNameNULL ist, ruft SetupDiGetClassPropertyEx die angeforderte Geräteklasseneigenschaft vom lokalen Computer ab.

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

SetupDiGetClassPropertyEx 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
ERROR_INVALID_FLAGS	Der Wert von Flags ist nicht 0 (null).
ERROR_INVALID_CLASS	Die von ClassGuid angegebene Gerätesetupklasse ist ungültig. Dieser Fehler kann nur auftreten, wenn das flag DICLASSPROP_INSTALLER angegeben ist.
ERROR_INVALID_PARAMETER	Ein nicht angegebener Parameter ist ungültig.
ERROR_INVALID_REG_PROPERTY	Der von PropertyKey bereitgestellte Eigenschaftenschlüssel ist ungültig.
ERROR_INVALID_REFERENCE_STRING	Die Referenzzeichenfolge der Geräteschnittstelle ist ungültig. Dieser Fehler kann zurückgegeben werden, wenn das flag DICLASSPROP_INTERFACE angegeben ist.
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 null ist.
ERROR_INVALID_MACHINENAME	Der computername, der von MachineName angegeben wird, ist ungültig.
ERROR_NO_SUCH_INTERFACE_CLASS	Die von ClassGuid angegebene Geräteschnittstellenklasse ist nicht vorhanden. Dieser Fehler kann nur auftreten, wenn das flag DICLASSPROP_INTERFACE angegeben ist.
ERROR_INSUFFICIENT_BUFFER	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

SetupDiGetClassPropertyEx ist Teil des einheitlichen Geräteeigenschaftenmodells.

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

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

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.

Um eine Geräteklasseneigenschaft auf einem lokalen Computer festzulegen, rufen Sie SetupDiSetClassProperty auf, und um eine Geräteklasseneigenschaft auf einem Remotecomputer festzulegen, rufen Sie SetupDiSetClassPropertyEx 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_Class_Property_ExW auf.
Kopfzeile	setupapi.h (schließen Sie Setupapi.h ein)
Bibliothek	Setupapi.lib