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 für einen 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 SetupDiGetClassDevs zurü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 NULL-beendete Zeichenfolge, die eine Verweiszeichenfolge bereitstellt. Dieser Zeiger ist optional und kann NULL sein. Verweiszeichenfolgen werden nur von wenigen 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 vom Aufrufer initialisierte SP_DEVICE_INTERFACE_DATA Struktur, um Informationen zur neuen Geräteschnittstelle zu erhalten. Dieser Zeiger ist optional und kann NULL sein. Wenn die Struktur angegeben wird, muss der Aufrufer das cbSize-Element dieser Struktur auf sizeof(SP_DEVICE_INTERFACE_DATA) festlegen, bevor diese Funktion aufgerufen wird. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise" .
Rückgabewert
SetupDiCreateDeviceInterface gibt TRUE zurück, wenn die Funktion ohne Fehler abgeschlossen wurde. Wenn die Funktion mit einem Fehler abgeschlossen wurde, gibt sie FALSE zurück, und der Fehlercode für den Fehler kann durch Aufrufen von GetLastError abgerufen werden.
Hinweise
Der Aufrufer dieser Funktion muss Mitglied der Gruppe Administratoren sein.
SetupDiCreateDeviceInterface registriert eine Schnittstelle für ein Gerät. Wenn ein Gerät über mehrere Schnittstellen verfügt, rufen Sie diese Funktion einmal für jede registrierte Schnittstelle auf.
Wenn diese Funktion erfolgreich eine Schnittstelle für das Gerät registriert, die dem angegebenen Geräteinformationselement entspricht, fügt sie die Schnittstelle auch der 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 mithilfe von SetupDiOpenDeviceInterfaceRegKey auf nichtvolatile Speicher unter diesem Schlüssel zugreifen.
Wenn SetupDiCreateDeviceInterface erfolgreich eine neue Geräteschnittstelle erstellt, aber der vom Aufrufer bereitgestellte Puffer im DeviceInterfaceData-Parameter ungültig ist, gibt diese Funktion FALSE zurück, und ein späterer Aufruf von GetLastError gibt ERROR_INVALID_USER_BUFFER zurück. Die Funktion erstellt und registriert jedoch die neue Geräteschnittstelle.
Hinweis
Der setupapi.h-Header 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 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
| Anforderung | Wert |
|---|---|
| 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 |