structure SP_DEVINSTALL_PARAMS_W (setupapi.h)
Une structure de SP_DEVINSTALL_PARAMS contient des paramètres d’installation d’appareil associés à un élément d’informations d’appareil particulier ou associés globalement à un ensemble d’informations d’appareil.
Syntaxe
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;
Membres
cbSize
Taille, en octets, de la structure SP_DEVINSTALL_PARAMS.
Flags
Indicateurs qui contrôlent les opérations d’installation et d’interface utilisateur. Certains indicateurs peuvent être définis avant l’envoi de la demande d’installation de l’appareil, tandis que d’autres indicateurs sont définis automatiquement pendant le traitement de certaines demandes. Les indicateurs peuvent être une combinaison des valeurs suivantes.
Les valeurs d’indicateur sont répertoriées dans des groupes : accessible en écriture par les programmes d’installation et les programmes d’installation d’appareil , lecture seule (définie uniquement par le système d’exploitation), réservée et obsolète. Le premier groupe répertorie les indicateurs qui peuvent être accessibles en écriture :
DI_CLASSINSTALLPARAMS
Définissez pour utiliser les paramètres d’installation de classe. SetupDiSetClassInstallParams définit cet indicateur lorsque l’appelant spécifie des paramètres et efface l’indicateur lorsque l’appelant spécifie un pointeur de paramètres NULL .
DI_COMPAT_FROM_CLASS
Définissez pour forcer SetupDiBuildDriverInfoList à créer la liste des pilotes compatibles d’un appareil à partir de sa liste de pilotes de classe au lieu du fichier INF.
DI_DRIVERPAGE_ADDED
Défini par un programme d’installation de classe ou un co-programme d’installation si le programme d’installation fournit une page qui remplace la page des propriétés du pilote fournie par le système. Si cet indicateur est défini, le système d’exploitation n’affiche pas la page du pilote fourni par le système.
DI_DONOTCALLCONFIGMG
Définissez si le gestionnaire de configuration ne doit pas être appelé pour supprimer ou énumérer des appareils pendant l’exécution de certaines fonctions d’installation d’appareil (par exemple, SetupDiInstallDevice).
Si cet indicateur est défini, les applications d’installation d’appareil, les programmes d’installation de classe et les co-programmes d’installation ne doivent pas appeler les fonctions suivantes :
CM_Reenumerate_DevNodeCM_Reenumerate_DevNode_ExCM_Query_And_Remove_SubTree CM_Query_And_Remove_SubTree_Ex CM_Setup_DevNodeCM_Setup_DevNode_ExCM_Set_HW_Prof_FlagsCM_Set_HW_Prof_Flags_ExCM_Enable_DevNodeCM_Enable_DevNode_ExCM_Disable_DevNodeCM_Disable_DevNode_Ex
DI_ENUMSINGLEINF
Définissez si les programmes d’installation et autres composants d’installation d’appareil doivent rechercher uniquement le fichier INF spécifié par SP_DEVINSTALL_PARAMS. DriverPath. Si cet indicateur est défini, DriverPath contient le chemin d’accès d’un seul fichier INF au lieu d’un chemin d’accès d’un répertoire.
DI_INF_IS_SORTED
Définissez pour indiquer que la page Sélectionner un appareil doit répertorier les pilotes dans l’ordre dans lequel ils apparaissent dans le fichier INF, au lieu de les trier par ordre alphabétique.
DI_INSTALLDISABLED
Définissez si l’appareil doit être installé dans un état désactivé par défaut. Pour être reconnu, cet indicateur doit être défini avant que Windows appelle le gestionnaire par défaut pour la requête DIF_INSTALLDEVICE .
DI_NEEDREBOOT
Pour les systèmes d’exploitation basés sur NT, cet indicateur est défini si l’appareil nécessite que l’ordinateur soit redémarré après l’installation de l’appareil ou un changement d’état de l’appareil. Un programme d’installation ou un co-programme d’installation de classe peut définir cet indicateur à tout moment pendant l’installation de l’appareil, si le programme d’installation détermine qu’un redémarrage est nécessaire.
DI_NEEDRESTART
Identique à DI_NEEDREBOOT.
DI_NOBROWSE
Définissez pour désactiver la navigation lorsque l’utilisateur sélectionne un chemin d’accès de disque OEM. Une application d’installation d’appareil définit cet indicateur pour contraindre un utilisateur à installer uniquement à partir de l’emplacement du support d’installation.
DI_NODI_DEFAULTACTION
Définissez si SetupDiCallClassInstaller ne doit pas effectuer d’action par défaut si le programme d’installation de classe retourne ERR_DI_DO_DEFAULT ou s’il n’existe pas de programme d’installation de classe.
DI_NOFILECOPY
Définissez si les composants et applications d’installation d’appareil, tels que SetupDiInstallDevice, doivent ignorer la copie de fichiers.
DI_NOVCP
Définissez pour désactiver la création d’une nouvelle file d’attente de copie. Utilisez la file d’attente de copie fournie par l’appelant dans SP_DEVINSTALL_PARAMS. FileQueue.
DI_NOWRITE_IDS
Défini pour empêcher SetupDiInstallDevice d’écrire les ID matériels spécifiés par INF et les ID compatibles dans les propriétés de l’appareil pour le nœud d’appareil (devnode). Cet indicateur ne doit être défini que pour les appareils énumérés par la racine.
Cet indicateur remplace l’indicateur DI_FLAGSEX_ALWAYSWRITEIDS.
DI_PROPERTIES_CHANGE
Défini par Gestionnaire de périphériques si les propriétés d’un appareil ont été modifiées, ce qui nécessite une mise à jour de l’interface utilisateur du programme d’installation.
DI_QUIETINSTALL
Définissez si les fonctions du programme d’installation de l’appareil doivent être silencieuses et utiliser les choix par défaut dans la mesure du possible. Les programmes d’installation et les co-programmes d’installation de classe ne doivent afficher aucune interface utilisateur si cet indicateur est défini.
DI_RESOURCEPAGE_ADDED
Défini par un programme d’installation ou un co-programme d’installation de classe si le programme d’installation fournit une page qui remplace la page des propriétés des ressources fournies par le système. Si cet indicateur est défini, le système d’exploitation n’affiche pas la page des ressources fournies par le système.
DI_SHOWOEM
Défini pour autoriser la prise en charge des disques OEM. Si cet indicateur est défini, le système d’exploitation présente un bouton « Avoir un disque » dans la page Sélectionner un appareil. Cet indicateur est défini, par défaut, dans les Assistants fournis par le système.
DI_USECI_SELECTSTRINGS
Définissez si un programme d’installation ou un co-programme d’installation de classe a fourni des chaînes qui doivent être utilisées pendant SetupDiSelectDevice.
Les indicateurs suivants sont en lecture seule (définis uniquement par le système d’exploitation) :
DI_DIDCLASS
Définissez si SetupDiBuildDriverInfoList a déjà créé une liste des pilotes pour cette classe d’appareil. Si cette liste a déjà été créée, elle contient toutes les informations du pilote et cet indicateur est toujours défini. SetupDiDestroyDriverInfoList efface cet indicateur lorsqu’il supprime une liste de pilotes pour une classe.
Cet indicateur est en lecture seule. Seul le système d’exploitation définit cet indicateur.
DI_DIDCOMPAT
Définissez si SetupDiBuildDriverInfoList a déjà créé une liste de pilotes compatibles pour cet appareil. Si cette liste a déjà été créée, elle contient toutes les informations du pilote et cet indicateur est toujours défini. SetupDiDestroyDriverInfoList efface cet indicateur lorsqu’il supprime une liste de pilotes compatibles.
Cet indicateur n’est défini que dans les paramètres d’installation de l’appareil qui sont associés à un élément d’informations d’appareil particulier, et non dans les paramètres d’un ensemble d’informations d’appareil.
Cet indicateur est en lecture seule. Seul le système d’exploitation définit cet indicateur.
DI_MULTMFGS
Défini par SetupDiBuildDriverInfoList si une liste de pilotes pour une classe d’installation d’appareil contient des pilotes fournis par plusieurs fabricants.
Cet indicateur est en lecture seule. Seul le système d’exploitation définit cet indicateur.
Les indicateurs suivants sont réservés :
DI_AUTOASSIGNRES
DI_DISABLED
DI_FORCECOPY
DI_GENERALPAGE_ADDED
DI_OVERRIDE_INFFLAGS
DI_SHOWALL
DI_SHOWCLASS
DI_SHOWCOMPAT
Les indicateurs suivants sont obsolètes :
DI_NOSELECTICONS
DI_PROPS_NOCHANGEUSAGE
FlagsEx
Indicateurs supplémentaires qui fournissent un contrôle sur les opérations d’installation et d’interface utilisateur. Certains indicateurs peuvent être définis avant d’appeler les fonctions du programme d’installation de l’appareil, tandis que d’autres indicateurs sont définis automatiquement pendant le traitement de certaines fonctions. FlagsEx peut être une combinaison des valeurs suivantes.
Les valeurs d’indicateur sont répertoriées en groupes : accessibles en écriture par les applications et programmes d’installation d’appareil, en lecture seule (définie uniquement par le système d’exploitation), réservés et obsolètes.
Le premier groupe répertorie les indicateurs accessibles en écriture :
DI_FLAGSEX_ALLOWEXCLUDEDDRVS
Si cette option est définie, incluez les pilotes marqués « Exclure de la sélection ».
Par exemple, si cet indicateur est défini, SetupDiSelectDevice affiche les pilotes dont l’état Exclure de la sélection et SetupDiBuildDriverInfoList inclut exclure des pilotes de la sélection dans la liste des pilotes demandés.
Un pilote est « Exclure de la sélection » s’il est marqué ExcludeFromSelect dans le fichier INF ou s’il s’agit d’un pilote pour un appareil dont l’ensemble de la classe d’installation est marqué NoInstallClass ou NoUseClass dans l’inf du programme d’installation de classe. Les pilotes pour les appareils PnP sont généralement « Exclure de la sélection » ; Les appareils PnP ne doivent pas être installés manuellement. Pour générer une liste de fichiers de pilotes pour un appareil PnP, un appelant de SetupDiBuildDriverInfoList doit définir cet indicateur.
DI_FLAGSEX_ALWAYSWRITEIDS
Si la valeur est définie et que l’indicateur DI_NOWRITE_IDS est clair, écrivez toujours du matériel et des ID compatibles dans les propriétés de l’appareil pour le devnode. Cet indicateur ne doit être défini que pour les appareils énumérés par la racine.
DI_FLAGSEX_APPENDDRIVERLIST
Si cette option est définie, SetupDiBuildDriverInfoList ajoute une nouvelle liste de pilotes à une liste existante. Cet indicateur est pertinent lors de la recherche de plusieurs emplacements.
DI_FLAGSEX_DRIVERLIST_FROM_URL
Si cette option est définie, générez la liste des pilotes à partir du ou des INF récupérés à partir de l’URL spécifiée dans SP_DEVINSTALL_PARAMS. DriverPath. Si DriverPath est une chaîne vide, utilisez le site web Windows Update.
Actuellement, le système d’exploitation ne prend pas en charge les URL. Utilisez cet indicateur pour diriger SetupDiBuildDriverInfoList pour effectuer une recherche sur le site web Windows Update.
Ne définissez pas cet indicateur si DI_QUIETINSTALL est défini.
DI_FLAGSEX_EXCLUDE_OLD_INET_DRIVERS
Si cette option est définie, n’incluez pas les anciens pilotes Internet lors de la création d’une liste de pilotes. Cet indicateur doit être défini chaque fois que vous créez une liste de pilotes potentiels pour un appareil. Vous pouvez effacer cet indicateur si vous obtenez simplement une liste des pilotes actuellement installés pour un appareil.
DI_FLAGSEX_FILTERCLASSES
Si cette option est définie, SetupDiBuildClassInfoList case activée pour les filtres d’inclusion de classe. Cela signifie qu’un appareil ne sera pas inclus dans la liste des classes si sa classe est marquée comme NoInstallClass.
DI_FLAGSEX_FILTERSIMILARDRIVERS
(Windows XP et versions ultérieures.) Si cette option est définie, SetupDiBuildDriverInfoList inclut des pilotes « similaires » lors de la création d’une liste de pilotes de classe. Un pilote « similaire » est un pilote pour lequel l’un des ID matériels ou des ID compatibles dans le fichier INF correspond partiellement (ou complètement) à l’un des ID matériels ou aux ID compatibles du matériel.
DI_FLAGSEX_FINISHINSTALL_ACTION
(Windows Vista et versions ultérieures.) Pour plus d’informations , consultez Marquage d’un appareil comme ayant une action Finish-Install à effectuer .
DI_FLAGSEX_INET_DRIVER
S’il est défini, le pilote a été obtenu à partir d’Internet. Windows n’utilisera pas l’INF de l’appareil pour installer de futurs appareils, car Windows ne peut pas garantir qu’il peut récupérer à nouveau les fichiers de pilote à partir d’Internet.
DI_FLAGSEX_INSTALLEDDRIVER
(Windows XP et versions ultérieures.) S’il est défini, SetupDiBuildDriverInfoList inclut uniquement le pilote actuellement installé lors de la création d’une liste de pilotes de classe ou de pilotes compatibles avec les périphériques.
DI_FLAGSEX_NO_CLASSLIST_NODE_MERGE
(Windows XP et versions ultérieures.) Si la valeur est définie, lors de la création d’une liste de pilotes de classe, SetupDiBuildDriverInfoList ne fusionne pas les nœuds de la liste de pilotes qui proviennent du même INF et qui ont la même description et le même classement du pilote.
DI_FLAGSEX_NO_DRVREG_MODIFY
Ne traitez pas les entrées AddReg et DelReg pour les clés matérielles et logicielles (pilotes) de l’appareil. Autrement dit, les entrées AddReg et DelReg dans les fichiers INF DDInstall et DDInstall. Sections HW .
DI_FLAGSEX_POWERPAGE_ADDED
Si cette option est définie, un programme d’installation a ajouté sa propre page pour la boîte de dialogue propriétés d’alimentation. Le système d’exploitation n’affiche pas la page des propriétés d’alimentation fournie par le système. Cet indicateur n’est pertinent que si l’appareil prend en charge la gestion de l’alimentation.
DI_FLAGSEX_PROPCHANGE_PENDING
Si cette option est définie, l’utilisateur a apporté des modifications à une ou plusieurs feuilles de propriétés d’appareil. Le fournisseur de pages de propriétés définit généralement cet indicateur.
Lorsque l’utilisateur ferme la feuille de propriétés de l’appareil, Gestionnaire de périphériques vérifie l’indicateur DI_FLAGSEX_PROPCHANGE_PENDING. S’il est défini, Gestionnaire de périphériques efface cet indicateur, définit l’indicateur DI_PROPERTIES_CHANGE et envoie une demande de DIF_PROPERTYCHANGE aux programmes d’installation pour les informer que quelque chose a changé.
DI_FLAGSEX_RECURSIVESEARCH
(Windows Vista et versions ultérieures.) Si la valeur est définie, lorsque SetupDiBuildDriverInfoList recherche des INF dans le chemin spécifié dans la valeur DriverPath , la recherche est récursive.
DI_FLAGSEX_SEARCH_PUBLISHED_INFS
(Windows Vista et versions ultérieures.) Si la valeur est définie, lorsque SetupDiBuildDriverInfoList est utilisé pour rechercher des INFs sans chemin d’accès INF ou chemin de recherche spécifié, la recherche est restreinte aux infs qui ont été importés dans le magasin de pilotes.
DI_FLAGSEX_SETFAILEDINSTALL
Définir si l’installation a échoué. Si cet indicateur est défini, la fonction SetupDiInstallDevice définit simplement l’indicateur FAILEDINSTALL dans la valeur de Registre ConfigFlags de l’appareil. Si DI_FLAGSEX_SETFAILEDINSTALL est défini, les co-programmes d’installation doivent retourner NO_ERROR en réponse à DIF_INSTALLDEVICE, tandis que les programmes d’installation de classe doivent retourner NO_ERROR ou ERROR_DI_DO_DEFAULT.
DI_FLAGSEX_USECLASSFORCOMPAT
Filtrez les fichiers INF sur la classe d’installation de l’appareil lors de la création d’une liste de pilotes compatibles. Si la classe d’installation d’un appareil est connue, la définition de cet indicateur réduit le temps nécessaire à la création d’une liste de pilotes compatibles lors de la recherche de fichiers INF qui ne sont pas précompilés. Cet indicateur est ignoré si DI_COMPAT_FROM_CLASS est défini.
Les indicateurs suivants sont en lecture seule : seul le système d’exploitation définit ces indicateurs :
DI_FLAGSEX_CI_FAILED
Défini par le système d’exploitation en cas d’échec du chargement ou du démarrage d’un programme d’installation de classe. Cet indicateur est en lecture seule.
DI_FLAGSEX_DIDCOMPATINFO
Windows a créé une liste de nœuds de pilotes compatibles avec l’appareil. Cet indicateur est en lecture seule.
DI_FLAGSEX_DIDINFOLIST
Windows a créé une liste de nœuds de pilotes qui inclut tous les pilotes répertoriés dans les fichiers INF de la classe d’installation spécifiée. Si la classe d’installation spécifiée est NULL , car le jeu ou le périphérique HDEVINFO n’a pas de classe associée, la liste inclut tous les nœuds de pilote de tous les fichiers INF disponibles. Cet indicateur est en lecture seule.
DI_FLAGSEX_IN_SYSTEM_SETUP
Si cette option est définie, l’installation se produit pendant la configuration initiale du système. Cet indicateur est en lecture seule.
Les indicateurs suivants sont réservés et ne doivent pas être utilisés :
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
Les indicateurs suivants sont obsolètes :
DI_FLAGSEX_AUTOSELECTRANK0
DI_FLAGSEX_NOUIONQUERYREMOVE
hwndParent
Handle de fenêtre qui possédera les boîtes de dialogue d’interface utilisateur associées à cet appareil.
InstallMsgHandler
Rappel utilisé pour gérer les événements lors de la copie de fichiers. Un programme d’installation peut utiliser un rappel, par exemple, pour effectuer un traitement spécial lors de la validation d’une file d’attente de fichiers.
InstallMsgHandlerContext
Données privées utilisées par le rappel InstallMsgHandler .
FileQueue
Handle d’une file d’attente de fichiers fournie par l’appelant dans laquelle les opérations de fichier doivent être mises en file d’attente, mais pas validées.
Si vous associez une file d’attente de fichiers à un jeu d’informations sur l’appareil (SetupDiSetDeviceInstallParams), vous devez dissocier la file d’attente du jeu d’informations sur l’appareil avant de supprimer le jeu d’informations sur l’appareil. Si vous ne parvenez pas à dissocier la file d’attente de fichiers, Windows ne peut pas décrémenter son nombre de références sur l’ensemble d’informations de l’appareil et ne peut pas libérer la mémoire.
Cette file d’attente est utilisée uniquement si l’indicateur DI_NOVCP est défini, ce qui indique que les opérations de fichier doivent être mises en file d’attente, mais pas validées.
ClassInstallReserved
Pointeur pour les données du programme d’installation de classe. Les co-programmes d’installation ne doivent pas utiliser ce champ.
Reserved
Réservé. À usage interne uniquement.
DriverPath[MAX_PATH]
Ce chemin est utilisé par la fonction SetupDiBuildDriverInfoList .
Remarques
Notes
L’en-tête setupapi.h définit SP_DEVINSTALL_PARAMS en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Configuration requise
| Condition requise | Valeur |
|---|---|
| En-tête | setupapi.h (inclure Setupapi.h) |