SetupDiCreateDeviceInfoA-Funktion (setupapi.h)
Die SetupDiCreateDeviceInfo-Funktion erstellt ein neues Geräteinformationselement und fügt es dem angegebenen Geräteinformationssatz als neues Element 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 zum Geräteinformationssatz für den lokalen Computer.
[in] DeviceName
Ein Zeiger auf eine MIT NULL beendete Zeichenfolge, die entweder eine vollständige Geräteinstanz-ID (z. B. "Root*PNP0500\0000") oder eine aufgezählte Geräte-ID ohne Enumeratorpräfix und Instanzbezeichnersuffix (z. B. "*PNP0500") bereitstellt. Der aufgezählte Gerätebezeichner kann nur verwendet werden, wenn das DICD_GENERATE_ID Flag im CreationFlags Parameter angegeben ist.
[in] ClassGuid
Ein Zeiger auf die Geräteeinrichtungsklasse GUID 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 MIT 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 auf oberster 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-werden.
[in] CreationFlags
Eine Variable vom Typ DWORD, die steuert, wie das Geräteinformationselement erstellt wird. Dies kann eine Kombination der folgenden Werte sein:
DICD_GENERATE_ID
Wenn dieses Flag angegeben ist, enthält DeviceName- nur eine Geräte-ID root-enumerated, und das System verwendet diese ID, um eine vollständige Geräteinstanz-ID für das neue Geräteinformationselement zu generieren.
Rufen Sie SetupDiGetDeviceInstanceId auf, um die Geräteinstanz-ID abzurufen, die für dieses Geräteinformationselement generiert wurde.
DICD_INHERIT_CLASSDRVS
Wenn dieses Flag angegeben ist, erbt das resultierende Geräteinformationselement die Klassentreiberliste( falls vorhanden), die dem Geräteinformationssatz zugeordnet ist. Wenn 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 bereitgestellt wird, muss der Aufrufer das cbSize Member dieser Struktur auf Sizeof(SP_DEVINFO_DATA ) festlegen, bevor die Funktion aufgerufen wird. Weitere Informationen finden Sie im folgenden abschnitt Anmerkungen.
Rückgabewert
Die Funktion gibt TRUE- zurück, wenn sie erfolgreich ist. Andernfalls wird FALSE- zurückgegeben, und der protokollierte Fehler kann abgerufen werden, indem ein Aufruf an GetLastError-ausgeführt wird.
Bemerkungen
Der Aufrufer dieser Funktion muss Mitglied der Gruppe "Administratoren" sein.
Wenn diese Geräteinstanz einem Satz hinzugefügt wird, der eine zugeordnete Klasse aufweist, muss die Geräteklasse identisch sein, oder der Anruf schlägt fehl. In diesem Fall gibt ein Aufruf von GetLastError ERROR_CLASS_MISMATCH zurück.
Wenn die angegebene Geräteinstanz mit einem vorhandenen Geräteinstanzschlü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 DICD_GENERATE_ID Flag nicht festgelegt ist.
Wenn das neue Geräteinformationselement erfolgreich erstellt wurde, aber der vom Aufrufer bereitgestellte DeviceInfoData- Puffer ungültig ist, gibt die Funktion FALSEzurü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.
Das DeviceInfoSet- darf nur Elemente auf dem lokalen Computer enthalten.
Anmerkung
Der header setupapi.h 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 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 Microsoft Windows 2000 und höheren Versionen von Windows. |
| Zielplattform- | Desktop |
| Header- | setupapi.h (include Setupapi.h) |
| Library | Setupapi.lib |