SetupDiGetDeviceInterfaceAlias-Funktion (setupapi.h)

  • Artikel

Die SetupDiGetDeviceInterfaceAlias-Funktion gibt einen Alias einer angegebenen Geräteschnittstelle zurück.

Syntax

WINSETUPAPI BOOL SetupDiGetDeviceInterfaceAlias(
  [in]  HDEVINFO                  DeviceInfoSet,
  [in]  PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData,
  [in]  const GUID                *AliasInterfaceClassGuid,
  [out] PSP_DEVICE_INTERFACE_DATA AliasDeviceInterfaceData
);

Parameter

[in] DeviceInfoSet

Ein Zeiger auf den Geräteinformationssatz , der die Geräteschnittstelle enthält, für die ein Alias abgerufen werden soll. Dieses Handle wird in der Regel von SetupDiGetClassDevs zurückgegeben.

[in] DeviceInterfaceData

Ein Zeiger auf eine SP_DEVICE_INTERFACE_DATA-Struktur , die die Geräteschnittstelle in DeviceInfoSet angibt, für die ein Alias abgerufen werden soll. Dieser Zeiger wird in der Regel von SetupDiEnumDeviceInterfaces zurückgegeben.

[in] AliasInterfaceClassGuid

Ein Zeiger auf eine GUID, die die Schnittstellenklasse des abzurufenden Alias angibt.

[out] AliasDeviceInterfaceData

Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, der bei erfolgreicher Rückgabe eine abgeschlossene SP_DEVICE_INTERFACE_DATA Struktur enthält, die den angeforderten Alias identifiziert. Der Aufrufer muss AliasDeviceInterfaceData.cbSize auf sizeof(SP_DEVICE_INTERFACE_DATA) festlegen, bevor diese Funktion aufgerufen wird.

Rückgabewert

SetupDiGetDeviceInterfaceAlias 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 von GetLastError abgerufen werden.

Mögliche Fehler, die von GetLastError zurückgegeben werden, sind in der folgenden Tabelle aufgeführt.

Rückgabecode Beschreibung
ERROR_INVALID_PARAMETER
 Ungültiger DeviceInfoSet - oder ungültiger DeviceInterfaceData-Parameter .
ERROR_NO_SUCH_INTERFACE_DEVICE
 Es gibt keinen Alias der Klasse AliasInterfaceClassGuid für die angegebene Geräteschnittstelle.
ERROR_INVALID_USER_BUFFER
 Ungültiger AliasDeviceInterfaceData-Puffer .

Hinweise

Geräteschnittstellen werden als Aliase betrachtet, wenn sie unterschiedlichen Schnittstellenklassen entsprechen, aber vom gleichen Gerät unterstützt werden und identische Verweiszeichenfolgen aufweisen.

SetupDiGetDeviceInterfaceAlias kann verwendet werden, um ein Gerät zu finden, das mehrere Schnittstellen verfügbar macht. Betrachten Sie beispielsweise einen Datenträger, der Teil eines fehlertoleranten Volumes sein kann und verschlüsselte Daten enthalten kann. Der Funktionstreiber für das Datenträgergerät könnte eine fehlertolerante Volumeschnittstelle und eine verschlüsselte Volumeschnittstelle registrieren. Diese Schnittstellen sind Geräteschnittstellenaliase, wenn der Funktionstreiber sie mit identischen Verweiszeichenfolgen registriert und auf dasselbe Gerät verweist. (Die Verweiszeichenfolgen sind wahrscheinlich NULL und daher gleich.)

Um ein solches Gerät mit mehreren Schnittstellen zu finden, suchen Sie zunächst alle verfügbaren Geräte, die eine der Schnittstellen verfügbar machen, z. B. die fehlertolerante Volumeschnittstelle, mithilfe von SetupDiGetClassDevs und SetupDiEnumDeviceInterfaces. Übergeben Sie dann ein Gerät mit der ersten Schnittstelle (fault-tolerant-volume) an SetupDiGetDeviceInterfaceAlias , und fordern Sie einen Alias der anderen Schnittstellenklasse (encrypted-volume) an.

Wenn der angeforderte Alias vorhanden ist, aber der vom Aufrufer bereitgestellte AliasDeviceInterfaceData-Puffer ungültig ist, fügt diese Funktion das Geräteschnittstellenelement zu DevInfoSet hinzu, gibt jedoch FALSE für den Rückgabewert zurück. In diesem Fall gibt GetLastError ERROR_INVALID_USER_BUFFER zurück.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Verfügbar in Microsoft Windows 2000 und höheren Versionen von Windows.
Zielplattform Desktop
Kopfzeile setupapi.h (schließen Sie Setupapi.h ein)
Bibliothek Setupapi.lib
DLL Setupapi.dll

Weitere Informationen

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs