Funzione SetupDiOpenDeviceInterfaceA (setupapi.h)

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 di 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 le relative funzioni correlate.

[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 richiesta. 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.

Osservazioni

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. Tuttavia, in questa situazione, SetupDiOpenDeviceInterface aggiunge l'interfaccia richiesta al set di informazioni sul dispositivo.

Se la nuova interfaccia del dispositivo viene aperta correttamente, ma il chiamante fornito buffer DeviceInterfaceData 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 di DIODI_NO_ADD viene specificato per il parametro OpenFlags e un elemento informazioni sul dispositivo sottostante non è già presente nel set di informazioni del dispositivo specificato, questa funzione restituisce false e GetLastError restituisce ERROR_NO_SUCH_DEVICE_INTERFACE.

Al termine dell'utilizzo delle informazioni SetupDiOpenDeviceInterface recuperate, 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.

Fabbisogno

Vedere anche

SetupDiDeleteDeviceInterfaceData

SetupDiEnumDeviceInterfaces