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.

Anforderungen

Weitere Informationen

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces