struttura SP_DEVINSTALL_PARAMS_W (setupapi.h)
Una struttura SP_DEVINSTALL_PARAMS contiene i parametri di installazione del dispositivo associati a un particolare elemento informazioni sul dispositivo o associati a livello globale a un set di informazioni sul dispositivo.
Sintassi
typedef struct _SP_DEVINSTALL_PARAMS_W {
DWORD cbSize;
DWORD Flags;
DWORD FlagsEx;
HWND hwndParent;
PSP_FILE_CALLBACK InstallMsgHandler;
PVOID InstallMsgHandlerContext;
HSPFILEQ FileQueue;
ULONG_PTR ClassInstallReserved;
DWORD Reserved;
WCHAR DriverPath[MAX_PATH];
} SP_DEVINSTALL_PARAMS_W, *PSP_DEVINSTALL_PARAMS_W;
Members
cbSize
Dimensione, in byte, della struttura SP_DEVINSTALL_PARAMS.
Flags
Flag che controllano le operazioni di installazione e interfaccia utente. Alcuni flag possono essere impostati prima di inviare la richiesta di installazione del dispositivo mentre altri flag vengono impostati automaticamente durante l'elaborazione di alcune richieste. I flag possono essere una combinazione dei valori seguenti.
I valori del flag sono elencati nei gruppi: scrivibili dalle applicazioni e dai programmi di installazione dei dispositivi, di sola lettura (solo impostati dal sistema operativo), riservati e obsoleti. Il primo gruppo elenca i flag scrivibili:
DI_CLASSINSTALLPARAMS
Impostare per usare i parametri Class Install. SetupDiSetClassInstallParams imposta questo flag quando il chiamante specifica i parametri e cancella il flag quando il chiamante specifica un puntatore ai parametri NULL .
DI_COMPAT_FROM_CLASS
Impostare per forzare SetupDiBuildDriverInfoList per compilare l'elenco di driver compatibili di un dispositivo dall'elenco dei driver di classe anziché dal file INF.
DI_DRIVERPAGE_ADDED
Impostato da un programma di installazione di classe o da un programma di installazione condivisa se il programma di installazione fornisce una pagina che sostituisce la pagina delle proprietà del driver fornita dal sistema. Se questo flag è impostato, il sistema operativo non visualizza la pagina del driver fornita dal sistema.
DI_DONOTCALLCONFIGMG
Impostare se configuration manager non deve essere chiamato per rimuovere o riesenumerare i dispositivi durante l'esecuzione di determinate funzioni di installazione del dispositivo, ad esempio SetupDiInstallDevice.
Se questo flag è impostato, le applicazioni di installazione del dispositivo, i programmi di installazione di classe e i coinstallazioni non devono chiamare le funzioni seguenti:
CM_Reenumerate_DevNodeCM_Reenumerate_DevNode_ExCM_Query_And_Remove_SubTreeCM_Query_And_Remove_SubTree_ExCM_Setup_DevNodeCM_Setup_DevNode_Ex CM_Set_HW_Prof_Flags CM_Set_HW_Prof_Flags_Ex CM_Enable_DevNode CM_Enable_DevNode_ExCM_Disable_DevNode CM_Disable_DevNode_Ex
DI_ENUMSINGLEINF
Impostare se i programmi di installazione e altri componenti di installazione del dispositivo devono cercare solo il file INF specificato da SP_DEVINSTALL_PARAMS. DriverPath. Se questo flag è impostato, DriverPath contiene il percorso di un singolo file INF anziché un percorso di una directory.
DI_INF_IS_SORTED
Impostare per indicare che la pagina Seleziona dispositivo deve elencare i driver nell'ordine in cui vengono visualizzati nel file INF, invece di ordinarli in ordine alfabetico.
DI_INSTALLDISABLED
Impostare se il dispositivo deve essere installato in uno stato disabilitato per impostazione predefinita. Per essere riconosciuto, questo flag deve essere impostato prima che Windows chiami il gestore predefinito per la richiesta di DIF_INSTALLDEVICE .
DI_NEEDREBOOT
Per i sistemi operativi basati su NT, questo flag viene impostato se il dispositivo richiede che il computer venga riavviato dopo l'installazione del dispositivo o una modifica dello stato del dispositivo. Un programma di installazione di classe o un programma di installazione condiviso può impostare questo flag in qualsiasi momento durante l'installazione del dispositivo, se il programma di installazione determina che è necessario un riavvio.
DI_NEEDRESTART
Uguale a DI_NEEDREBOOT.
DI_NOBROWSE
Impostare per disabilitare l'esplorazione quando l'utente seleziona un percorso del disco OEM. Un'applicazione di installazione del dispositivo imposta questo flag per vincolare un utente all'installazione solo dal percorso del supporto di installazione.
DI_NODI_DEFAULTACTION
Impostare se SetupDiCallClassInstaller non deve eseguire alcuna azione predefinita se il programma di installazione della classe restituisce ERR_DI_DO_DEFAULT o non è presente un programma di installazione della classe.
DI_NOFILECOPY
Impostare se le applicazioni e i componenti di installazione del dispositivo, ad esempio SetupDiInstallDevice, devono ignorare la copia dei file.
DI_NOVCP
Impostare per disabilitare la creazione di una nuova coda di copia. Usare la coda di copia fornita dal chiamante in SP_DEVINSTALL_PARAMS. FileQueue.
DI_NOWRITE_IDS
Impostare per impedire a SetupDiInstallDevice di scrivere gli ID hardware specificati inF e gli ID compatibili nelle proprietà del dispositivo per il nodo del dispositivo (devnode). Questo flag deve essere impostato solo per i dispositivi enumerati alla radice.
Questo flag esegue l'override del flag DI_FLAGSEX_ALWAYSWRITEIDS.
DI_PROPERTIES_CHANGE
Impostato da Gestione dispositivi se le proprietà di un dispositivo sono state modificate, che richiede un aggiornamento dell'interfaccia utente del programma di installazione.
DI_QUIETINSTALL
Impostare se le funzioni del programma di installazione del dispositivo devono essere invisibile all'utente e usare le scelte predefinite laddove possibile. I programmi di installazione di classe e i co-installer non devono visualizzare alcuna interfaccia utente se questo flag è impostato.
DI_RESOURCEPAGE_ADDED
Impostata da un programma di installazione classi o da un programma di installazione condivisa se il programma di installazione fornisce una pagina che sostituisce la pagina delle proprietà delle risorse fornite dal sistema. Se questo flag è impostato, il sistema operativo non visualizza la pagina della risorsa fornita dal sistema.
DI_SHOWOEM
Impostare per consentire il supporto per i dischi OEM. Se questo flag è impostato, il sistema operativo presenta un pulsante "Have Disk" nella pagina Seleziona dispositivo. Questo flag è impostato, per impostazione predefinita, nelle procedure guidate fornite dal sistema.
DI_USECI_SELECTSTRINGS
Impostare se un programma di installazione di classe o una stringa fornita dal programma di installazione condivisa che deve essere usata durante SetupDiSelectDevice.
I flag seguenti sono di sola lettura (solo impostati dal sistema operativo):
DI_DIDCLASS
Impostare se SetupDiBuildDriverInfoList ha già compilato un elenco dei driver per questa classe di dispositivo. Se questo elenco è già stato compilato, contiene tutte le informazioni sul driver e questo flag viene sempre impostato. SetupDiDestroyDriverInfoList cancella questo flag quando elimina un elenco di driver per una classe.
Questo flag è di sola lettura. Solo il sistema operativo imposta questo flag.
DI_DIDCOMPAT
Impostare se SetupDiBuildDriverInfoList ha già creato un elenco di driver compatibili per questo dispositivo. Se questo elenco è già stato compilato, contiene tutte le informazioni sul driver e questo flag viene sempre impostato. SetupDiDestroyDriverInfoList cancella questo flag quando elimina un elenco di driver compatibile.
Questo flag viene impostato solo nei parametri di installazione del dispositivo associati a un particolare elemento di informazioni sul dispositivo, non nei parametri per un set di informazioni sul dispositivo nel suo complesso.
Questo flag è di sola lettura. Solo il sistema operativo imposta questo flag.
DI_MULTMFGS
Impostato da SetupDiBuildDriverInfoList se un elenco di driver per una classe di installazione del dispositivo contiene driver forniti da più produttori.
Questo flag è di sola lettura. Solo il sistema operativo imposta questo flag.
I flag seguenti sono riservati:
DI_AUTOASSIGNRES
DI_DISABLED
DI_FORCECOPY
DI_GENERALPAGE_ADDED
DI_OVERRIDE_INFFLAGS
DI_SHOWALL
DI_SHOWCLASS
DI_SHOWCOMPAT
I flag seguenti sono obsoleti:
DI_NOSELECTICONS
DI_PROPS_NOCHANGEUSAGE
FlagsEx
Flag aggiuntivi che forniscono il controllo sulle operazioni di installazione e interfaccia utente. Alcuni flag possono essere impostati prima di chiamare le funzioni del programma di installazione del dispositivo mentre altri flag vengono impostati automaticamente durante l'elaborazione di alcune funzioni. FlagsEx può essere una combinazione dei valori seguenti.
I valori del flag sono elencati nei gruppi: scrivibili dalle applicazioni e dai programmi di installazione dei dispositivi, di sola lettura (solo impostati dal sistema operativo), riservati e obsoleti.
Il primo gruppo elenca i flag scrivibili:
DI_FLAGSEX_ALLOWEXCLUDEDDRVS
Se impostato, includere i driver contrassegnati come "Escludi da seleziona".
Ad esempio, se questo flag è impostato, SetupDiSelectDevice visualizza i driver con lo stato Exclude From Select e SetupDiBuildDriverInfoList include Exclude From Select driver nell'elenco dei driver richiesti.
Un driver è "Exclude From Select" se è contrassegnato come ExcludeFromSelect nel file INF oppure è un driver per un dispositivo il cui intero programma di installazione è contrassegnato come NoInstallClass o NoUseClass nel programma di installazione della classe INF. I driver per i dispositivi PnP sono in genere "Escludi da seleziona"; I dispositivi PnP non devono essere installati manualmente. Per compilare un elenco di file driver per un dispositivo PnP, è necessario impostare questo flag per un chiamante di SetupDiBuildDriverInfoList .
DI_FLAGSEX_ALWAYSWRITEIDS
Se impostato e il flag di DI_NOWRITE_IDS è chiaro, scrivere sempre ID hardware e compatibili nelle proprietà del dispositivo per devnode. Questo flag deve essere impostato solo per i dispositivi enumerati alla radice.
DI_FLAGSEX_APPENDDRIVERLIST
Se impostato, SetupDiBuildDriverInfoList aggiunge un nuovo elenco di driver a un elenco esistente. Questo flag è rilevante per la ricerca in più posizioni.
DI_FLAGSEX_DRIVERLIST_FROM_URL
Se impostato, compilare l'elenco di driver da INF(s) recuperato dall'URL specificato in SP_DEVINSTALL_PARAMS. DriverPath. Se DriverPath è una stringa vuota, usare il sito Web Windows Update.
Attualmente, il sistema operativo non supporta gli URL. Usare questo flag per indirizzare SetupDiBuildDriverInfoList a cercare il sito Web di Windows Update.
Non impostare questo flag se è impostato DI_QUIETINSTALL.
DI_FLAGSEX_EXCLUDE_OLD_INET_DRIVERS
Se impostata, non includere i vecchi driver Internet durante la compilazione di un elenco di driver. Questo flag deve essere impostato ogni volta che si sta creando un elenco di potenziali driver per un dispositivo. È possibile cancellare questo flag se si ottiene solo un elenco di driver attualmente installati per un dispositivo.
DI_FLAGSEX_FILTERCLASSES
Se impostato, SetupDiBuildClassInfoList verificherà la presenza di filtri di inclusione della classe. Ciò significa che un dispositivo non verrà incluso nell'elenco di classi se la relativa classe è contrassegnata come NoInstallClass.
DI_FLAGSEX_FILTERSIMILARDRIVERS
(Windows XP e versioni successive). Se impostato, SetupDiBuildDriverInfoList include driver "simili" durante la compilazione di un elenco di driver di classe. Un driver "simile" è uno dei quali uno degli ID hardware o gli ID compatibili nel file INF parzialmente (o completamente) corrisponde a uno degli ID hardware o ID compatibili dell'hardware.
DI_FLAGSEX_FINISHINSTALL_ACTION
(Windows Vista e versioni successive). Per altre informazioni, vedere Contrassegnare un dispositivo come un'azione di Finish-Install da eseguire .
DI_FLAGSEX_INET_DRIVER
Se impostato, il driver è stato ottenuto da Internet. Windows non userà l'INF del dispositivo per installare i dispositivi futuri perché Windows non può garantire che possa recuperare nuovamente i file driver da Internet.
DI_FLAGSEX_INSTALLEDDRIVER
(Windows XP e versioni successive). Se impostato, SetupDiBuildDriverInfoList include solo il driver attualmente installato durante la creazione di un elenco di driver di classe o driver compatibili con il dispositivo.
DI_FLAGSEX_NO_CLASSLIST_NODE_MERGE
(Windows XP e versioni successive). Se impostato, quando si crea un elenco di driver di classe, SetupDiBuildDriverInfoList non unisce nodi nell'elenco di driver che provengono dallo stesso INF e hanno la stessa descrizione e classificazione del driver.
DI_FLAGSEX_NO_DRVREG_MODIFY
Non elaborare le voci AddReg e DelReg per le chiavi hardware e software (driver) del dispositivo. Ovvero, le voci AddReg e DelReg nel file INF DDInstall e DDInstall. Sezioni HW .
DI_FLAGSEX_POWERPAGE_ADDED
Se impostato, un programma di installazione ha aggiunto la propria pagina per la finestra di dialogo delle proprietà di alimentazione. Il sistema operativo non visualizzerà la pagina delle proprietà di alimentazione fornita dal sistema. Questo flag è rilevante solo se il dispositivo supporta il risparmio energia.
DI_FLAGSEX_PROPCHANGE_PENDING
Se impostato, l'utente ha apportato modifiche a una o più finestre delle proprietà del dispositivo. Il provider di pagine delle proprietà imposta in genere questo flag.
Quando l'utente chiude la finestra delle proprietà del dispositivo, Gestione dispositivi controlla il flag DI_FLAGSEX_PROPCHANGE_PENDING. Se è impostato, Gestione dispositivi cancella questo flag, imposta il flag DI_PROPERTIES_CHANGE e invia una richiesta di DIF_PROPERTYCHANGE ai programmi di installazione per notificare che è stato modificato un elemento.
DI_FLAGSEX_RECURSIVESEARCH
(Windows Vista e versioni successive). Se impostato, quando SetupDiBuildDriverInfoList cerca le funzioni INFS nel percorso specificato nel valore driverPath , la ricerca sarà ricorsiva.
DI_FLAGSEX_SEARCH_PUBLISHED_INFS
(Windows Vista e versioni successive). Se impostata, quando SetupDiBuildDriverInfoList viene usato per cercare infs senza un percorso INF o un percorso di ricerca specificato, questa impostazione limita la ricerca solo agli INFS importati nell'archivio driver.
DI_FLAGSEX_SETFAILEDINSTALL
Impostare se l'installazione non è riuscita. Se questo flag è impostato, la funzione SetupDiInstallDevice imposta solo il flag FAILEDINSTALL nel valore del Registro di sistema ConfigFlags del dispositivo. Se DI_FLAGSEX_SETFAILEDINSTALL è impostato, i co-installer devono restituire NO_ERROR in risposta a DIF_INSTALLDEVICE, mentre i programmi di installazione delle classi devono restituire NO_ERROR o ERROR_DI_DO_DEFAULT.
DI_FLAGSEX_USECLASSFORCOMPAT
Filtrare i file INF nella classe di installazione del dispositivo durante la compilazione di un elenco di driver compatibili. Se la classe di installazione di un dispositivo è nota, l'impostazione di questo flag riduce il tempo necessario per compilare un elenco di driver compatibili durante la ricerca di file INF non precompilati. Questo flag viene ignorato se è impostato DI_COMPAT_FROM_CLASS.
I flag seguenti sono di sola lettura; solo il sistema operativo imposta questi flag:
DI_FLAGSEX_CI_FAILED
Impostato dal sistema operativo se un programma di installazione della classe non è riuscito a caricare o avviare. Questo flag è di sola lettura.
DI_FLAGSEX_DIDCOMPATINFO
Windows ha creato un elenco di nodi driver compatibili con il dispositivo. Questo flag è di sola lettura.
DI_FLAGSEX_DIDINFOLIST
Windows ha creato un elenco di nodi driver che include tutti i driver elencati nei file INF della classe di installazione specificata. Se la classe di installazione specificata è NULL perché il set o il dispositivo HDEVINFO non ha alcuna classe associata, l'elenco include tutti i nodi driver di tutti i file INF disponibili. Questo flag è di sola lettura.
DI_FLAGSEX_IN_SYSTEM_SETUP
Se impostato, l'installazione viene eseguita durante l'installazione iniziale del sistema. Questo flag è di sola lettura.
I flag seguenti sono riservati e non devono essere usati:
DI_FLAGSEX_ALTPLATFORM_DRVSEARCH
DI_FLAGSEX_BACKUPONREPLACE
DI_FLAGSEX_DEVICECHANGE
DI_FLAGSEX_OLDINF_IN_CLASSLIST
DI_FLAGSEX_PREINSTALLBACKUP
DI_FLAGSEX_RESTART_DEVICE_ONLY
DI_FLAGSEX_USEOLDINFSEARCH
I flag seguenti sono obsoleti:
DI_FLAGSEX_AUTOSELECTRANK0
DI_FLAGSEX_NOUIONQUERYREMOVE
hwndParent
Handle di finestra che sarà proprietario delle finestre di dialogo dell'interfaccia utente correlate a questo dispositivo.
InstallMsgHandler
Callback usato per gestire gli eventi durante la copia di file. Un programma di installazione può usare un callback, ad esempio, per eseguire un'elaborazione speciale durante il commit di una coda di file.
InstallMsgHandlerContext
Dati privati usati dal callback InstallMsgHandler .
FileQueue
Handle per una coda di file fornita dal chiamante in cui le operazioni sui file devono essere accodate ma non sottoposte a commit.
Se si associa una coda di file a un set di informazioni sul dispositivo (SetupDiSetDeviceInstallParams), è necessario annullare l'associazione della coda dal set di informazioni sul dispositivo prima di eliminare il set di informazioni sul dispositivo. Se non si annulla l'associazione della coda di file, Windows non può decrementare il conteggio dei riferimenti nel set di informazioni sul dispositivo e non può liberare la memoria.
Questa coda viene usata solo se il flag DI_NOVCP è impostato, a indicare che le operazioni sui file devono essere accodate ma non sottoposte a commit.
ClassInstallReserved
Puntatore per i dati del programma di installazione di classe. I co-programmi di installazione non devono utilizzare questo campo.
Reserved
Riservato. Solo per uso interno.
DriverPath[MAX_PATH]
Questo percorso viene usato dalla funzione SetupDiBuildDriverInfoList .
Commenti
Nota
L'intestazione setupapi.h definisce SP_DEVINSTALL_PARAMS 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 |
|---|---|
| Intestazione | setupapi.h (include Setupapi.h) |