Fonction SetupPromptForDiskA (setupapi.h)

Article
08/26/2023

[Cette fonction est disponible pour une utilisation dans les systèmes d’exploitation indiqués dans la section Configuration requise. Il sera peut-être modifié ou indisponible dans les versions ultérieures. SetupAPI ne doit plus être utilisé pour l’installation d’applications. Utilisez plutôt Windows Installer pour développer des programmes d’installation d’applications. SetupAPI continue d’être utilisé pour l’installation des pilotes de périphérique.]

La fonction SetupPromptForDisk affiche une boîte de dialogue qui invite l’utilisateur à entrer un disque.

Syntaxe

WINSETUPAPI UINT SetupPromptForDiskA(
  [in]      HWND   hwndParent,
  [in]      PCSTR  DialogTitle,
  [in]      PCSTR  DiskName,
  [in]      PCSTR  PathToSource,
  [in]      PCSTR  FileSought,
  [in]      PCSTR  TagFile,
  [in]      DWORD  DiskPromptStyle,
  [in, out] PSTR   PathBuffer,
  [in]      DWORD  PathBufferSize,
  [in, out] PDWORD PathRequiredSize
);

Paramètres

[in] hwndParent

Gérer vers la fenêtre parente de cette boîte de dialogue.

[in] DialogTitle

Pointeur facultatif vers une chaîne terminée par null spécifiant le titre de la boîte de dialogue. Si ce paramètre a la valeur NULL, la valeur par défaut « "%s-Files Needed" » (localisée) est utilisée. Le « %s » est remplacé par le texte récupéré à partir de la fenêtre parente. Si aucun texte n’est récupéré à partir de la fenêtre parente, le titre est « Fichiers nécessaires ».

[in] DiskName

Pointeur facultatif vers une chaîne terminée par null spécifiant le nom du disque à insérer. Si ce paramètre a la valeur NULL, la valeur par défaut « (Inconnu) » (localisée) est utilisée.

[in] PathToSource

Pointeur facultatif vers une chaîne terminée par null spécifiant la partie de chemin d’accès de l’emplacement attendu du fichier, par exemple, F :\x86. S’il n’est pas spécifié, le chemin d’accès où SetupPromptForDisk a récemment localisé un fichier est utilisé. Si cette liste est vide, une valeur par défaut système est utilisée.

[in] FileSought

Pointeur vers une chaîne terminée par null spécifiant le nom du fichier nécessaire (partie de nom de fichier uniquement). Le nom de fichier s’affiche si l’utilisateur clique sur le bouton Parcourir . Cette routine recherche le fichier à l’aide de ses noms de formulaire compressé ; Par conséquent, vous pouvez passer cmd.exe et ne pas vous soucier que le fichier existe réellement en tant que cmd.ex_ sur le média source.

[in] TagFile

Pointeur facultatif vers une chaîne terminée par null spécifiant un fichier de balise (partie de nom de fichier uniquement) qui identifie la présence d’un volume multimédia amovible particulier. Si le chemin d’accès actuellement sélectionné place le fichier sur un support amovible et qu’un fichier de balise est spécifié, SetupPromptForDisk recherche le fichier de balise à la racine du lecteur pour déterminer s’il faut continuer.

Par exemple, si PathToSource est A :\x86, que le tagfile est disk1.tag et que l’utilisateur tape B :\x86 dans le contrôle d’édition de la boîte de dialogue d’invite, la routine recherche B :\disk1.tag pour déterminer s’il faut continuer. Si le fichier de balise est introuvable, la fonction recherche le tagfile à l’aide de PathToSource.

Si aucun fichier de balise n’est spécifié, le média amovible fonctionne comme un média non amovible et FileSought est recherché avant de continuer.

[in] DiskPromptStyle

Spécifie le comportement de la boîte de dialogue. Ce paramètre peut être une combinaison des indicateurs suivants.

IDF_CHECKFIRST

Recherchez le fichier/disque avant d’afficher la boîte de dialogue d’invite et, le cas échéant, retournez immédiatement DPROMPT_SUCCESS.

IDF_NOBEEP

Empêchez la boîte de dialogue de biper pour attirer l’attention de l’utilisateur lorsqu’elle apparaît pour la première fois.

IDF_NOBROWSE

N’affichez pas l’option parcourir.

IDF_NOCOMPRESSED

Ne case activée pas pour les versions compressées du fichier source.

IDF_NODETAILS

N’affichez pas d’informations détaillées.

IDF_NOFOREGROUND

Empêchez la boîte de dialogue de devenir la fenêtre de premier plan.

IDF_NOSKIP

N’affichez pas l’option ignorer.

IDF_OEMDISK

Demander un disque fourni par un fabricant de matériel.

IDF_WARNIFSKIP

Avertir l’utilisateur que l’omission d’un fichier peut affecter l’installation.

[in, out] PathBuffer

Pointeur facultatif vers une mémoire tampon qui, au retour, reçoit le chemin d’accès (aucun nom de fichier) de l’emplacement spécifié par l’utilisateur via la boîte de dialogue. Vous devez utiliser une chaîne terminée par null. La chaîne terminée par null ne doit pas dépasser la taille de la mémoire tampon de destination. Vous pouvez appeler la fonction une fois pour obtenir la taille de mémoire tampon requise, allouer la mémoire nécessaire, puis appeler la fonction une deuxième fois pour récupérer les données. À l’aide de cette technique, vous pouvez éviter les erreurs dues à une taille de mémoire tampon insuffisante. Consultez la section Notes.

[in] PathBufferSize

Taille de la mémoire tampon pointée vers pathBuffer, en caractères. Il devrait être au moins MAX_PATH long. Cela inclut le terminateur null .

[in, out] PathRequiredSize

Pointeur facultatif vers une variable qui reçoit la taille requise pour PathBuffer, en caractères. Cela inclut le terminateur null .

Valeur retournée

La fonction retourne l’une des valeurs suivantes.

Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

Si cette fonction est appelée avec un PathBuffernull et un PathBufferSize de zéro, la fonction place la taille de mémoire tampon nécessaire pour contenir les données spécifiées dans la variable pointée par PathRequiredSize. Si la fonction réussit cette opération, la valeur de retour est NO_ERROR. Sinon, la valeur de retour est l’une des valeurs décrites dans la section Valeurs de retour.

Notes

L’en-tête setupapi.h définit SetupPromptForDisk comme un 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. Le mélange 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
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	setupapi.h
Bibliothèque	Setupapi.lib
DLL	Setupapi.dll