Funzione SetupDiGetDeviceInterfaceDetailA (setupapi.h)

Articolo
03/15/2023

La funzione SetupDiGetDeviceInterfaceDetail restituisce dettagli su un'interfaccia del dispositivo.

Sintassi

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
);

Parametri

[in] DeviceInfoSet

Puntatore al set di informazioni sul dispositivo che contiene l'interfaccia per cui recuperare i dettagli. Questo handle viene in genere restituito da SetupDiGetClassDevs.

[in] DeviceInterfaceData

Puntatore a una struttura SP_DEVICE_INTERFACE_DATA che specifica l'interfaccia in DeviceInfoSet per cui recuperare i dettagli. Un puntatore di questo tipo viene in genere restituito da SetupDiEnumDeviceInterfaces.

[out, optional] DeviceInterfaceDetailData

Puntatore a una struttura SP_DEVICE_INTERFACE_DETAIL_DATA per ricevere informazioni sull'interfaccia specificata. Questo parametro è facoltativo e può essere NULL. Questo parametro deve essere NULL se DeviceInterfaceDetailSize è zero. Se questo parametro è specificato, il chiamante deve impostare DeviceInterfaceDetailData.cbSize su sizeof(SP_DEVICE_INTERFACE_DETAIL_DATA) prima di chiamare questa funzione. Il membro cbSize contiene sempre le dimensioni della parte fissa della struttura dati, non una dimensione che riflette la stringa di lunghezza variabile alla fine.

[in] DeviceInterfaceDetailDataSize

Dimensioni del buffer DeviceInterfaceDetailData . Il buffer deve essere almeno (offsetof(SP_DEVICE_INTERFACE_DETAIL_DATA, DevicePath) + sizeof(TCHAR)) byte, per contenere la parte fissa della struttura e un singolo NULL per terminare una stringa di MULTI_SZ vuota.

Questo parametro deve essere zero se DeviceInterfaceDetailData è NULL.

[out, optional] RequiredSize

Puntatore a una variabile di tipo DWORD che riceve le dimensioni necessarie del buffer DeviceInterfaceDetailData . Questa dimensione include le dimensioni della parte fissa della struttura e il numero di byte necessari per la stringa del percorso del dispositivo a lunghezza variabile. Questo parametro è facoltativo e può essere NULL.

[out, optional] DeviceInfoData

Puntatore a un buffer che riceve informazioni sul dispositivo che supporta l'interfaccia richiesta. Il chiamante deve impostare DeviceInfoData.cbSize su sizeof(SP_DEVINFO_DATA). Questo parametro è facoltativo e può essere NULL.

Valore restituito

SetupDiGetDeviceInterfaceDetail restituisceTRUE se la funzione è stata completata senza errore. Se la funzione è stata completata con un errore, FALSE viene restituito e il codice di errore per l'errore può essere recuperato chiamando GetLastError.

Commenti

L'uso di questa funzione per ottenere informazioni dettagliate su un'interfaccia è in genere un processo in due passaggi:

Ottenere le dimensioni del buffer necessarie. Chiamare SetupDiGetDeviceInterfaceDetail con un puntatore NULL DeviceInterfaceDetailData, un puntatore DeviceInterfaceDetailDataSize di zero e una variabile RequiredSize valida. In risposta a tale chiamata, questa funzione restituisce le dimensioni del buffer necessarie in RequiredSize e non riesce con GetLastError che restituisce ERROR_INSUFFICIENT_BUFFER.
Allocare un buffer di dimensioni appropriate e chiamare di nuovo la funzione per ottenere i dettagli dell'interfaccia.

I dettagli dell'interfaccia restituiti da questa funzione sono costituiti da un percorso del dispositivo che può essere passato alle funzioni Win32, ad esempio CreateFile. Non tentare di analizzare il nome simbolico del percorso del dispositivo. Il percorso del dispositivo può essere riutilizzato nell'avvio del sistema.

SetupDiGetDeviceInterfaceDetail può essere usato per ottenere solo DeviceInfoData. Se l'interfaccia esiste ma DeviceInterfaceDetailData è NULL, questa funzione ha esito negativo, GetLastError restituisce ERROR_INSUFFICIENT_BUFFER e la struttura DeviceInfoData viene riempita con informazioni sul dispositivo che espone l'interfaccia.

Nota

L'intestazione setupapi.h definisce SetupDiGetDeviceInterfaceDetail come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Disponibile in Microsoft Windows 2000 e versioni successive di Windows.
Piattaforma di destinazione	Desktop
Intestazione	setupapi.h (includere Setupapi.h)
Libreria	Setupapi.lib

Vedi anche

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs

Share via