Condividi tramite

Funzione SetupDiOpenDeviceInterfaceA (setupapi.h)

  • Articolo

La funzione SetupDiOpenDeviceInterface recupera informazioni su un'interfaccia del dispositivo e aggiunge l'interfaccia al set di informazioni sul dispositivo specificato per un sistema locale o un sistema remoto.

Sintassi

WINSETUPAPI BOOL SetupDiOpenDeviceInterfaceA(
  [in]            HDEVINFO                  DeviceInfoSet,
  [in]            PCSTR                     DevicePath,
  [in]            DWORD                     OpenFlags,
  [out, optional] PSP_DEVICE_INTERFACE_DATA DeviceInterfaceData
);

Parametri

[in] DeviceInfoSet

Puntatore a un set di informazioni sul dispositivo che contiene o conterrà un elemento informazioni sul dispositivo che rappresenta il dispositivo che supporta l'interfaccia da aprire.

[in] DevicePath

Puntatore a una stringa con terminazione NULL che fornisce il nome dell'interfaccia del dispositivo da aprire. Questo nome è un percorso del dispositivo Win32 che viene in genere ricevuto in una struttura di notifica PnP o ottenuto da una chiamata precedente a SetupDiEnumDeviceInterfaces e alle relative funzioni.

[in] OpenFlags

Flag che determinano la modalità di apertura dell'elemento dell'interfaccia del dispositivo. L'unico flag valido è il seguente:

DIODI_NO_ADD

Specifica che l'elemento informazioni sul dispositivo per il dispositivo sottostante non verrà creato se tale elemento non è già presente nel set di informazioni sul dispositivo specificato. Per altre informazioni, vedere la sezione Osservazioni seguente.

[out, optional] DeviceInterfaceData

Puntatore a una struttura di SP_DEVICE_INTERFACE_DATA inizializzata dal chiamante che riceve i dati dell'interfaccia richiesti. Questo puntatore è facoltativo e può essere NULL. Se viene fornito un buffer, il chiamante deve impostare il membro cbSize della struttura su sizeof(SP_DEVICE_INTERFACE_DATA) prima di chiamare SetupDiOpenDeviceInterface. Per altre informazioni, vedere la sezione Osservazioni seguente.

Valore restituito

SetupDiOpenDeviceInterface restituisce TRUE se la funzione è stata completata senza errori. Se la funzione è stata completata con un errore, restituisce FALSE e il codice di errore per l'errore può essere recuperato chiamando GetLastError.

Commenti

Se un elemento dell'interfaccia del dispositivo per l'interfaccia esiste già in DeviceInfoSet, SetupDiOpenDeviceInterface aggiorna i flag. Questa funzione può quindi essere usata per aggiornare i flag per un'interfaccia del dispositivo. Ad esempio, un'interfaccia potrebbe essere stata inattiva quando è stata aperta per la prima volta, ma successivamente è diventata attiva. Se l'elemento informazioni sul dispositivo sottostante non è già presente in DeviceInfoSet, questa funzione ne crea una e la aggiunge a DeviceInfoSet.

Se la funzione apre correttamente la nuova interfaccia del dispositivo, ma il chiamante non ha fornito una struttura valida nel parametro DeviceInterfaceData , la funzione restituirà FALSE e una chiamata successiva a GetLastError restituirà ERROR_INVALID_USER_BUFFER. In questa situazione, tuttavia, SetupDiOpenDeviceInterface aggiunge l'interfaccia richiesta al set di informazioni sul dispositivo.

Se la nuova interfaccia del dispositivo viene aperta correttamente, ma il buffer DeviceInterfaceData fornito dal chiamante non è valido, questa funzione restituisce FALSE e GetLastError restituisce ERROR_INVALID_USER_BUFFER. L'errore del buffer del chiamante non impedisce l'apertura dell'interfaccia.

Se il flag DIODI_NO_ADD viene specificato per il parametro OpenFlags e un elemento informazioni sul dispositivo sottostante non è già presente nel set di informazioni sul dispositivo specificato, questa funzione restituisce FALSE e GetLastError restituisce ERROR_NO_SUCH_DEVICE_INTERFACE.

Al termine dell'uso delle informazioni recuperate da SetupDiOpenDeviceInterface, l'applicazione deve chiamare SetupDiDeleteDeviceInterfaceData.

MF_DEVSOURCE_ATTRIBUTE_SOURCE_TYPE_VIDCAP_SYMBOLIC_LINK attributo può essere passato come valore dell'argomento DevicePath della funzione SetupDiOpenDeviceInterface .

Nota

L'intestazione setupapi.h definisce SetupDiOpenDeviceInterface 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

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

Vedi anche

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces