Funzione SetupDiInstallDevice (setupapi.h)

Articolo
08/26/2023

La funzione SetupDiInstallDevice è il gestore predefinito per la richiesta di installazione DIF_INSTALLDEVICE .

Sintassi

WINSETUPAPI BOOL SetupDiInstallDevice(
  [in]      HDEVINFO         DeviceInfoSet,
  [in, out] PSP_DEVINFO_DATA DeviceInfoData
);

Parametri

[in] DeviceInfoSet

Handle per il set di informazioni sul dispositivo per il sistema locale che contiene un elemento di informazioni sul dispositivo che rappresenta il dispositivo da installare.

[in, out] DeviceInfoData

Puntatore a una struttura SP_DEVINFO_DATA che specifica un elemento informazioni sul dispositivo in DeviceInfoSet. Si tratta di un parametro IN-OUT perché DeviceInfoData.DevInst potrebbe essere aggiornato con un nuovo valore handle al momento della restituzione.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce TRUE . In caso contrario, restituisce FALSE e l'errore registrato può essere recuperato con una chiamata a GetLastError.

Commenti

SetupDiInstallDevice installa un driver dal file INF. La definizione di SetupAPI del "driver" è in realtà un "nodo driver". Pertanto, quando questa funzione installa un driver, installa anche gli elementi nell'elenco seguente:

I servizi per il dispositivo.
File del driver.
Co-installer specifici del dispositivo (se presenti).
Provider di pagine delle proprietà (se presenti).
Applet del pannello di controllo (se presenti).

Questa funzione registra anche tutte le interfacce di dispositivo necessarie.

Una corretta installazione include, ma non solo, i passaggi seguenti:

Creare una chiave del driver nel Registro di sistema e scrivere le voci appropriate, ad esempio InfPath e ProviderName.
Individuare ed elaborare la sezione INF DDInstall per il dispositivo. La sezione potrebbe essere specifica del sistema operativo o dell'architettura. Le voci AddReg e DelReg della sezione DDInstall vengono indirizzate alla chiave software del dispositivo. Individuare ed elaborare DDInstall. Sezione HW le cui voci AddReg e DelReg vengono indirizzate alla chiave hardware del dispositivo. Individuare ed elaborare la sezione INF DDInstall.LogConfigOverride, se presente, per fornire una configurazione di override per il dispositivo. Individuare ed elaborare la sezione INF DDInstall.Services per aggiungere servizi per il dispositivo e rimuovere potenzialmente eventuali servizi obsoleti che non sono più necessari.
Copiare il file INF nella directory INF di sistema.
È possibile eseguire le altre operazioni sui file, in base alle impostazioni del flag nei parametri di installazione del dispositivo.
Se il flag DI_NOFILECOPY e il flag DI_NOVCP sono chiari, eseguire qualsiasi operazione di file specificata nella sezione DDInstall . Se il flag DI_NOVCP è impostato, accoda tutte le operazioni sui file.

Se il flag DI_NOFILECOPY è impostato, non copiare i file. Questo flag può essere impostato se, ad esempio, è già stata eseguita un'operazione di DIF_INSTALLDEVICEFILES per l'installazione del dispositivo.
Caricare i driver per il dispositivo. Sono inclusi il driver di funzione e qualsiasi driver di filtro superiore o inferiore.
Chiamare le routine AddDevice dei driver.
Avviare il dispositivo inviando un pacchetto di richiesta I/O IRP_MN_START_DEVICE .

Windows non avvia il dispositivo se il flag DI_NEEDRESTART, DI_NEEDREBOOT o DI_DONOTCALLCONFIGMG è impostato nella struttura SP_DEVINSTALL_PARAMS .

Un programma di installazione classi deve restituire ERROR_DI_DO_DEFAULT o chiamare questa funzione durante la gestione di una richiesta di DIF_INSTALLDEVICE . Questa funzione esegue molte attività per l'installazione del dispositivo e tale elenco di attività potrebbe essere espanso nelle versioni future. Se un programma di installazione di classe esegue l'installazione del dispositivo senza chiamare questa funzione, il programma di installazione della classe potrebbe non funzionare correttamente nelle versioni future del sistema operativo.

Se Windows non riesce a individuare un file INF per il dispositivo, invierà DIF_INSTALLDEVICE nel tentativo di installare un driver Null. SetupDiInstallDevice installa un driver Null solo se il dispositivo supporta la modalità non elaborata o è un dispositivo non PnP (segnalato da IoReportDetectedDevice). Per altre informazioni, vedere DIF_INSTALLDEVICE.

Se il flag DI_FLAGSEX_SETFAILEDINSTALL è impostato nella struttura SP_DEVINSTALL_PARAMS , SetupDiInstallDevice imposta solo il flag FAILEDINSTALL nel valore del Registro di sistema ConfigFlags del dispositivo.

Nota Solo un programma di installazione di classe deve chiamare SetupDiInstallDevice e solo in quelle situazioni in cui il programma di installazione della classe deve eseguire operazioni di installazione del dispositivo dopo che SetupDiInstallDevice completa l'operazione di installazione predefinita del dispositivo. In tali situazioni, il programma di installazione della classe deve chiamare direttamente SetupDiInstallDevice quando il programma di installazione elabora una richiesta di DIF_INSTALLDEVICE. Per altre informazioni sulla chiamata al gestore predefinito, vedere Chiamata di gestori di codice DIF predefiniti.

Il chiamante di SetupDiInstallDevice deve essere membro del gruppo Administrators.

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
DLL	Setupapi.dll

Vedi anche

DIF_INSTALLDEVICE

SetupDiCallClassInstaller

SetupDiInstallDriverFiles

Condividi tramite