Funzione SetupDiGetDeviceInterfaceDetailA (setupapi.h)

Articolo
11/20/2024

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 si specifica questo parametro, 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 di dati, non una dimensione che riflette la stringa a 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 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 DeviceInterfaceDetail Data. Queste dimensioni includono le dimensioni della parte fissa della struttura e il numero di byte necessari per la stringa di 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 restituisce true se la funzione è stata completata senza errori. Se la funzione è stata completata con un errore, viene restituita false e il codice di errore per l'errore può essere recuperato chiamando GetLastError.

Osservazioni

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 NULLDeviceInterfaceDetailData puntatore, un DeviceInterfaceDetailDataSize pari a zero e una variabile RequiredSize valida. In risposta a una chiamata di questo tipo, questa funzione restituisce le dimensioni del buffer necessarie a RequiredSize e ha esito negativo 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 all'avvio del sistema.

SetupDiGetDeviceInterfaceDetail per ottenere solo il DeviceInfoData. Se l'interfaccia esiste ma DeviceInterfaceDetailData è null, questa funzione ha esito negativo, GetLastError restituisce ERROR_INSUFFICIENT_BUFFER e la struttura DeviceInfoData viene compilata 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile in Microsoft Windows 2000 e versioni successive di Windows.
piattaforma di destinazione	Desktop
intestazione	setupapi.h (include Setupapi.h)
libreria	Setupapi.lib

Vedere anche

SetupDiEnumDeviceInterfaces

SetupDiGetClassDevs

Condividi tramite