SetupDiGetDeviceInterfaceDetailA-Funktion (setupapi.h)

Artikel
11/20/2024

Die SetupDiGetDeviceInterfaceDetail--Funktion gibt Details zu einer Geräteschnittstelle zurück.

Syntax

WINSETUPAPI BOOL SetupDiGetDeviceInterfaceDetailA(
  [in]            HDEVINFO                           DeviceInfoSet,
  [in]            PSP_DEVICE_INTERFACE_DATA          DeviceInterfaceData,
  [out, optional] PSP_DEVICE_INTERFACE_DETAIL_DATA_A DeviceInterfaceDetailData,
  [in]            DWORD                              DeviceInterfaceDetailDataSize,
  [out, optional] PDWORD                             RequiredSize,
  [out, optional] PSP_DEVINFO_DATA                   DeviceInfoData
);

Parameter

[in] DeviceInfoSet

Ein Zeiger auf den Geräteinformationssatz, der die Schnittstelle enthält, für die Details abgerufen werden sollen. Dieses Handle wird in der Regel von SetupDiGetClassDevszurückgegeben.

[in] DeviceInterfaceData

Ein Zeiger auf eine SP_DEVICE_INTERFACE_DATA Struktur, die die Schnittstelle in DeviceInfoSet- angibt, für die Details abgerufen werden sollen. Ein Zeiger dieses Typs wird in der Regel von SetupDiEnumDeviceInterfaceszurückgegeben.

[out, optional] DeviceInterfaceDetailData

Ein Zeiger auf eine SP_DEVICE_INTERFACE_DETAIL_DATA Struktur, um Informationen über die angegebene Schnittstelle zu empfangen. Dieser Parameter ist optional und kann NULL-werden. Dieser Parameter muss NULL- sein, wenn DeviceInterfaceDetailSize null ist. Wenn dieser Parameter angegeben ist, muss der Aufrufer DeviceInterfaceDetailData.cbSize auf Sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) festlegen, bevor diese Funktion aufgerufen wird. Das cbSize Member enthält immer die Größe des festen Teils der Datenstruktur, nicht eine Größe, die die Zeichenfolge variabler Länge am Ende widerspiegelt.

[in] DeviceInterfaceDetailDataSize

Die Größe des DeviceInterfaceDetailData- Puffers. Der Puffer muss mindestens (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + Sizeof(TCHAR)) byte sein, um den festen Teil der Struktur und einen einzelnen NULL- enthalten, um eine leere MULTI_SZ Zeichenfolge zu beenden.

Dieser Parameter muss null sein, wenn DeviceInterfaceDetailData-NULL-ist.

[out, optional] RequiredSize

Ein Zeiger auf eine Variable vom Typ DWORD, die die erforderliche Größe des DeviceInterfaceDetailData- Puffers empfängt. Diese Größe enthält die Größe des festen Teils der Struktur sowie die Anzahl der Bytes, die für die Zeichenfolge für den Gerätepfad mit variabler Länge erforderlich sind. Dieser Parameter ist optional und kann NULL-werden.

[out, optional] DeviceInfoData

Ein Zeiger auf einen Puffer, der Informationen über das Gerät empfängt, das die angeforderte Schnittstelle unterstützt. Der Aufrufer muss DeviceInfoData.cbSize- auf Größe(SP_DEVINFO_DATA) festlegen. Dieser Parameter ist optional und kann NULL-werden.

Rückgabewert

SetupDiGetDeviceInterfaceDetail- 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

Die Verwendung dieser Funktion zum Abrufen von Details zu einer Schnittstelle ist in der Regel ein zweistufiger Prozess:

Rufen Sie die erforderliche Puffergröße ab. Rufen Sie SetupDiGetDeviceInterfaceDetail- mit einem NULL-DeviceInterfaceDetailData Zeiger, einem DeviceInterfaceDetailDataSize null und einer gültigen RequiredSize Variable auf. Als Reaktion auf einen solchen Aufruf gibt diese Funktion die erforderliche Puffergröße bei RequiredSize zurück und schlägt mit GetLastError rückgabenden ERROR_INSUFFICIENT_BUFFER fehl.
Weisen Sie einen entsprechend großen Puffer zu, und rufen Sie die Funktion erneut auf, um die Schnittstellendetails abzurufen.

Das von dieser Funktion zurückgegebene Schnittstellendetail besteht aus einem Gerätepfad, der an Win32-Funktionen wie CreateFile-übergeben werden kann. Versuchen Sie nicht, den symbolischen Namen des Gerätepfads zu analysieren. Der Gerätepfad kann über Systemstarts hinweg wiederverwendet werden.

SetupDiGetDeviceInterfaceDetail- kann verwendet werden, um nur die DeviceInfoData-abzurufen. Wenn die Schnittstelle vorhanden ist, DeviceInterfaceDetailData jedoch NULL-ist, schlägt diese Funktion fehl, GetLastError gibt ERROR_INSUFFICIENT_BUFFER zurück, und die DeviceInfoData- Struktur wird mit Informationen zum Gerät gefüllt, das die Schnittstelle verfügbar macht.

Anmerkung

Der Header setupapi.h definiert SetupDiGetDeviceInterfaceDetail 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

Siehe auch

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs-

Freigeben über