SetupDiOpenDeviceInterfaceW-Funktion (setupapi.h)
Die SetupDiOpenDeviceInterface--Funktion ruft Informationen zu einer Geräteschnittstelle ab und fügt die Schnittstelle zum angegebenen Geräteinformationssatz für ein lokales System oder ein Remotesystem hinzu.
Syntax
WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceW(
[in] HDEVINFO DeviceInfoSet,
[in] PCWSTR DevicePath,
[in] DWORD OpenFlags,
[out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);
Parameter
[in] DeviceInfoSet
Ein Zeiger auf einen Geräteinformationssatz, der ein Geräteinformationselement enthält oder enthält, das das Gerät darstellt, das die zu öffnende Schnittstelle unterstützt.
[in] DevicePath
Ein Zeiger auf eine MIT NULL beendete Zeichenfolge, die den Namen der zu öffnenden Geräteschnittstelle angibt. Dieser Name ist ein Win32-Gerätepfad, der in der Regel in einer PnP-Benachrichtigungsstruktur empfangen wird oder durch einen vorherigen Aufruf von SetupDiEnumDeviceInterfaces und den zugehörigen Funktionen abgerufen wird.
[in] OpenFlags
Flags, die bestimmen, wie das Geräteschnittstellenelement geöffnet werden soll. Die einzige gültige Kennzeichnung lautet wie folgt:
DIODI_NO_ADD
Gibt an, dass das Geräteinformationselement für das zugrunde liegende Gerät nicht erstellt wird, wenn dieses Element nicht bereits im angegebenen Geräteinformationssatzvorhanden ist. Weitere Informationen finden Sie im folgenden abschnitt Anmerkungen.
[out, optional] DeviceInterfaceData
Ein Zeiger auf eine vom Aufrufer initialisierte SP_DEVICE_INTERFACE_DATA Struktur, die die angeforderten Schnittstellendaten empfängt. Dieser Zeiger ist optional und kann NULL-sein. Wenn ein Puffer bereitgestellt wird, muss der Aufrufer das cbSize Member der Struktur auf Sizeof(SP_DEVICE_INTERFACE_DATA ) festlegen, bevor SetupDiOpenDeviceInterfaceaufgerufen wird. Weitere Informationen finden Sie im folgenden abschnitt Anmerkungen.
Rückgabewert
SetupDiOpenDeviceInterface- 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
Wenn bereits ein Geräteschnittstellenelement für die Schnittstelle in DeviceInfoSet-vorhanden ist, aktualisiert SetupDiOpenDeviceInterface die Flags. Daher kann diese Funktion verwendet werden, um die Flags für eine Geräteschnittstelle zu aktualisieren. Beispielsweise könnte eine Schnittstelle beim ersten Öffnen inaktiv gewesen sein, wurde aber anschließend aktiv. Wenn das Geräteinformationselement für das zugrunde liegende Gerät noch nicht in DeviceInfoSet-vorhanden ist, erstellt diese Funktion ein Element und fügt es DeviceInfoSethinzu.
Wenn die Funktion die neue Geräteschnittstelle erfolgreich öffnet, der Aufrufer jedoch keine gültige Struktur im DeviceInterfaceData- Parameter angegeben hat, gibt die Funktion FALSE- zurück, und ein anschließender Aufruf von GetLastError- gibt ERROR_INVALID_USER_BUFFER zurück. In diesem Fall fügt SetupDiOpenDeviceInterface- die angeforderte Schnittstelle zum Geräteinformationssatz hinzu.
Wenn die neue Geräteschnittstelle erfolgreich geöffnet wurde, der vom Aufrufer bereitgestellte DeviceInterfaceData- Puffer ungültig ist, gibt diese Funktion FALSE- zurück, und GetLastError- gibt ERROR_INVALID_USER_BUFFER zurück. Der Pufferfehler des Aufrufers verhindert nicht, dass die Schnittstelle geöffnet wird.
Wenn das DIODI_NO_ADD Flag für den OpenFlags Parameter angegeben ist und ein Geräteinformationselement für das zugrunde liegende Gerät nicht bereits im angegebenen Geräteinformationssatzvorhanden ist, gibt diese Funktion FALSE zurück und GetLastError gibt ERROR_NO_SUCH_DEVICE_INTERFACE zurück.
Wenn die Anwendung die Informationen verwendet hat, die SetupDiOpenDeviceInterface abgerufen, muss die Anwendung SetupDiDeleteDeviceInterfaceDataaufrufen.
MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK Attribut kann als Wert des DevicePath--Arguments des SetupDiOpenDeviceInterface--Funktion übergeben werden.
Anmerkung
Der Header "setupapi.h" definiert SetupDiOpenDeviceInterface 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 |