SetupDiOpenDeviceInterfaceA-Funktion (setupapi.h)
Die SetupDiOpenDeviceInterface-Funktion ruft Informationen zu einer Geräteschnittstelle ab und fügt die Schnittstelle dem angegebenen Geräteinformationssatz für ein lokales System oder ein Remotesystem hinzu.
Syntax
WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
[in] HDEVINFO DeviceInfoSet,
[in] PCSTR 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, das das Gerät darstellt, das das Öffnen der Schnittstelle unterstützt.
[in] DevicePath
Ein Zeiger auf eine 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 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. Das einzige gültige Flag 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äteinformationssatz vorhanden ist. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise" .
[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 angegeben wird, muss der Aufrufer das cbSize-Element der Struktur auf sizeof(SP_DEVICE_INTERFACE_DATA) festlegen, bevor SetupDiOpenDeviceInterface aufgerufen wird. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise" .
Rückgabewert
SetupDiOpenDeviceInterface 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
Wenn in DeviceInfoSet bereits ein Geräteschnittstellenelement für die Schnittstelle vorhanden ist, aktualisiert SetupDiOpenDeviceInterface die Flags. Daher kann diese Funktion verwendet werden, um die Flags für eine Geräteschnittstelle zu aktualisieren. Beispielsweise war eine Schnittstelle beim ersten Öffnen möglicherweise inaktiv, 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 eines und fügt es DeviceInfoSet hinzu.
Wenn die Funktion die neue Geräteschnittstelle erfolgreich öffnet, der Aufrufer jedoch keine gültige Struktur im DeviceInterfaceData-Parameter bereitgestellt hat, gibt die Funktion FALSE zurück, und ein späterer Aufruf von GetLastError gibt ERROR_INVALID_USER_BUFFER zurück. In dieser Situation fügt SetupDiOpenDeviceInterface dem Geräteinformationssatz jedoch die angeforderte Schnittstelle hinzu.
Wenn die neue Geräteschnittstelle erfolgreich geöffnet wurde, aber 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 noch nicht im angegebenen Geräteinformationssatz vorhanden ist, gibt diese Funktion FALSE zurück, und GetLastError gibt ERROR_NO_SUCH_DEVICE_INTERFACE zurück.
Wenn die Anwendung die von SetupDiOpenDeviceInterface abgerufenen Informationen verwendet hat, muss die Anwendung SetupDiDeleteDeviceInterfaceData aufrufen.
MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK-Attribut kann als Wert des DevicePath-Arguments der SetupDiOpenDeviceInterface-Funktion übergeben werden.
Hinweis
Der setupapi.h-Header definiert SetupDiOpenDeviceInterface als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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 |