SetupDiCreateDeviceInterfaceA-Funktion (setupapi.h)
Die SetupDiCreateDeviceInterface-Funktion registriert eine Geräteschnittstelle auf einem lokalen System oder einem Remotesystem.
Syntax
WINSETUPAPI BOOL SetupDiCreateDeviceInterfaceA(
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in] const GUID *InterfaceClassGuid,
[in, optional] PCSTR ReferenceString,
[in] DWORD CreationFlags,
[out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);
Parameter
[in] DeviceInfoSet
Ein Handle zu einem Geräteinformationssatz. Dieser Satz enthält ein Geräteinformationselement, das das Gerät darstellt, für das eine Schnittstelle registriert werden soll. Dieses Handle wird in der Regel von SetupDiGetClassDevszurückgegeben.
[in] DeviceInfoData
Ein Zeiger auf eine SP_DEVINFO_DATA Struktur, die das Geräteinformationselement in DeviceInfoSet-angibt.
[in] InterfaceClassGuid
Ein Zeiger auf eine Klassen-GUID, die die Schnittstellenklasse für die neue Schnittstelle angibt.
[in, optional] ReferenceString
Ein Zeiger auf eine MIT NULL beendete Zeichenfolge, die eine Referenzzeichenfolge bereitstellt. Dieser Zeiger ist optional und kann NULL-sein. Referenzzeichenfolgen werden nur von einigen Bustreibern verwendet, die Geräteschnittstellen als Platzhalter für Softwaregeräte verwenden, die bei Bedarf erstellt werden.
[in] CreationFlags
Reserviert. Muss null sein.
[out, optional] DeviceInterfaceData
Ein Zeiger auf eine aufruferinitialisierte SP_DEVICE_INTERFACE_DATA Struktur, um Informationen zur neuen Geräteschnittstelle zu erhalten. Dieser Zeiger ist optional und kann NULL-sein. Wenn die Struktur bereitgestellt wird, muss der Aufrufer das cbSize Member dieser Struktur auf Sizeof(SP_DEVICE_INTERFACE_DATA ) festlegen, bevor diese Funktion aufgerufen wird. Weitere Informationen finden Sie im folgenden abschnitt Anmerkungen.
Rückgabewert
SetupDiCreateDeviceInterface gibt TRUE zurück, wenn die Funktion ohne Fehler abgeschlossen wurde. Wenn die Funktion mit einem Fehler abgeschlossen wurde, wird FALSE- zurückgegeben, und der Fehlercode für den Fehler kann durch Aufrufen GetLastErrorabgerufen werden.
Bemerkungen
Der Aufrufer dieser Funktion muss Mitglied der Gruppe "Administratoren" sein.
SetupDiCreateDeviceInterface registriert eine Schnittstelle für ein Gerät. Wenn ein Gerät mehrere Schnittstellen aufweist, rufen Sie diese Funktion einmal für jede registrierte Schnittstelle auf.
Wenn diese Funktion erfolgreich eine Schnittstelle für das Gerät registriert, das dem angegebenen Geräteinformationselement entspricht, fügt sie auch die Schnittstelle zur Schnittstellenliste hinzu, die dem Geräteinformationselement im angegebenen Geräteinformationssatz zugeordnet ist.
Bevor eine registrierte Schnittstelle von Anwendungen und anderen Systemkomponenten verwendet werden kann, muss die Schnittstelle vom Treiber für das Gerät aktiviert werden.
Diese Funktion erstellt einen Registrierungsschlüssel für die neue Geräteschnittstelle. Aufrufer dieser Funktion können mit SetupDiOpenDeviceInterfaceRegKeyauf nichtvolatile Speicher unter diesem Schlüssel zugreifen.
Wenn SetupDiCreateDeviceInterface erfolgreich eine neue Geräteschnittstelle erstellt, der vom Aufrufer bereitgestellte Puffer im DeviceInterfaceData-Parameter jedoch ungültig ist, gibt diese Funktion FALSE- zurück, und ein anschließender Aufruf von GetLastError gibt ERROR_INVALID_USER_BUFFER zurück. Die Funktion erstellt und registriert jedoch die neue Geräteschnittstelle.
Anmerkung
Der Header setupapi.h definiert SetupDiCreateDeviceInterface 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 |