SetupDiCreateDeviceInfoA-Funktion (setupapi.h)

Artikel
08/26/2023

Die SetupDiCreateDeviceInfo-Funktion erstellt ein neues Geräteinformationselement und fügt es als neues Element zum angegebenen Geräteinformationssatz hinzu.

Syntax

WINSETUPAPI BOOL SetupDiCreateDeviceInfoA(
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PCSTR            DeviceName,
  [in]            const GUID       *ClassGuid,
  [in, optional]  PCSTR            DeviceDescription,
  [in, optional]  HWND             hwndParent,
  [in]            DWORD            CreationFlags,
  [out, optional] PSP_DEVINFO_DATA DeviceInfoData
);

Parameter

[in] DeviceInfoSet

Ein Handle für die Geräteinformationen, die für den lokalen Computer festgelegt sind.

[in] DeviceName

Ein Zeiger auf eine NULL-beendete Zeichenfolge, die entweder eine vollständige Geräte-instance-ID (z. B. "Root*PNP0500\0000") oder eine stammumerierte Geräte-ID ohne das Enumeratorpräfix und instance Bezeichnersuffix (z. B. "*PNP0500") bereitstellt. Der root-enumerierte Gerätebezeichner kann nur verwendet werden, wenn das DICD_GENERATE_ID-Flag im CreationFlags-Parameter angegeben ist.

[in] ClassGuid

Ein Zeiger auf die GUID der Geräteeinrichtungsklasse für das Gerät. Wenn die Gerätesetupklasse des Geräts nicht bekannt ist, legen Sie *ClassGuid auf eine GUID_NULL-Struktur fest.

[in, optional] DeviceDescription

Ein Zeiger auf eine NULL-beendete Zeichenfolge, die die Textbeschreibung des Geräts bereitstellt. Dieser Zeiger ist optional und kann NULL sein.

[in, optional] hwndParent

Ein Handle für das Fenster der obersten Ebene, das für jede Benutzeroberfläche verwendet werden soll, die sich auf die Installation des Geräts bezieht. Dieses Handle ist optional und kann NULL sein.

[in] CreationFlags

Eine Variable vom Typ DWORD, die steuert, wie das Geräteinformationselement erstellt wird. Kann eine Kombination der folgenden Werte sein:

DICD_GENERATE_ID

Wenn dieses Flag angegeben ist, enthält DeviceName nur eine root-enumerierte Geräte-ID, und das System verwendet diese ID, um eine vollständige Geräte-instance-ID für das neue Geräteinformationselement zu generieren.

Rufen Sie SetupDiGetDeviceInstanceId auf, um die Geräte-instance-ID abzurufen, die für dieses Geräteinformationselement generiert wurde.

DICD_INHERIT_CLASSDRVS

Wenn dieses Flag angegeben wird, erbt das resultierende Geräteinformationselement die Klassentreiberliste, falls vorhanden, die dem Geräteinformationssatz zugeordnet ist. Wenn außerdem ein ausgewählter Treiber für den Geräteinformationssatz vorhanden ist, wird derselbe Treiber für das neue Geräteinformationselement ausgewählt.

[out, optional] DeviceInfoData

Ein Zeiger auf eine SP_DEVINFO_DATA-Struktur , die das neue Geräteinformationselement empfängt. Dieser Zeiger ist optional und kann NULL sein. Wenn die Struktur angegeben wird, muss der Aufrufer den cbSize-Member dieser Struktur auf sizeof(SP_DEVINFO_DATA) festlegen, bevor die Funktion aufgerufen wird. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise" .

Rückgabewert

Die Funktion gibt TRUE zurück, wenn sie erfolgreich ist. Andernfalls wird FALSE zurückgegeben, und der protokollierte Fehler kann durch einen Aufruf von GetLastError abgerufen werden.

Hinweise

Der Aufrufer dieser Funktion muss Mitglied der Gruppe Administratoren sein.

Wenn dieses Gerät instance einer Gruppe hinzugefügt wird, die über eine zugeordnete Klasse verfügt, muss die Geräteklasse identisch sein, andernfalls schlägt der Aufruf fehl. In diesem Fall gibt ein Aufruf von GetLastError ERROR_CLASS_MISMATCH zurück.

Wenn das angegebene Gerät instance mit einem vorhandenen Geräte instance Schlüssel in der Registrierung identisch ist, schlägt der Aufruf fehl. In diesem Fall gibt ein Aufruf von GetLastError ERROR_DEVINST_ALREADY_EXISTS zurück. Dies tritt nur auf, wenn das flag DICD_GENERATE_ID nicht festgelegt ist.

Wenn das neue Geräteinformationselement erfolgreich erstellt wurde, aber der vom Aufrufer bereitgestellte DeviceInfoData-Puffer ungültig ist, gibt die Funktion FALSE zurück. In diesem Fall gibt ein Aufruf von GetLastError ERROR_INVALID_USER_BUFFER zurück. Das Geräteinformationselement wurde jedoch bereits als neues Element der Gruppe hinzugefügt.

DeviceInfoSet darf nur Elemente auf dem lokalen Computer enthalten.

Hinweis

Der setupapi.h-Header definiert SetupDiCreateDeviceInfo 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 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


Unterstützte Mindestversion (Client)	Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform	Desktop
Kopfzeile	setupapi.h (einschließlich Setupapi.h)
Bibliothek	Setupapi.lib