Fonction SetupScanFileQueueA (setupapi.h)
[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 SetupScanFileQueue analyse une file d’attente de fichiers d’installation, en effectuant une opération sur chaque nœud de sa liste de copie. L’opération est spécifiée par un ensemble d’indicateurs. Cette fonction peut être appelée avant ou après la validation de la file d’attente.
Syntaxe
WINSETUPAPI BOOL SetupScanFileQueueA(
[in] HSPFILEQ FileQueue,
[in] DWORD Flags,
[in] HWND Window,
[in] PSP_FILE_CALLBACK_A CallbackRoutine,
[in] PVOID CallbackContext,
[out] PDWORD Result
);
Paramètres
[in] FileQueue
Gérez la file d’attente du fichier d’installation dont la liste de copie doit être analysée ou itérée.
[in] Flags
Indicateurs à combiner pour contrôler l’opération d’analyse de file d’attente de fichiers. Notez que SPQ_SCAN_FILE_PRESENCE, SPQ_SCAN_USE_CALLBACK, SPQ_SCAN_USE_CALLBACKEX ou SPQ_SCAN_FILE_VALIDITY doivent être spécifiés.
| Indicateur | Signification |
|---|---|
|
Les fichiers cibles de la file d’attente de copie sont déjà présents sur la cible. |
|
Les fichiers cibles de la file d’attente de copie sont déjà présents sur la cible avec des signatures valides. Disponible avec Windows 2000 et versions ultérieures. |
|
Routine de rappel pour chaque nœud de la file d’attente. Si la routine de rappel retourne une valeur différente de zéro, le traitement de la file d’attente s’arrête et SetupScanFileQueue retourne zéro. Émettez un code de notification SPFILENOTIFY_QUEUESCAN et passez un pointeur vers le chemin cible en tant que Param1. |
|
Routine de rappel pour chaque nœud de la file d’attente. Si la routine de rappel retourne une valeur différente de zéro, le traitement de la file d’attente s’arrête et SetupScanFileQueue retourne zéro. Émettez une notification SPFILENOTIFY_QUEUESCAN_EX et passez un pointeur vers une structure FILEPATHS en tant que Param1. SPQ_SCAN_USE_CALLBACKEX vérifie également que le fichier a une signature valide. Disponible à partir de Windows 2000. Sur Windows XP uniquement, vous pouvez désactiver la vérification des signatures en combinant cet indicateur avec SPQ_SCAN_FILE_PRESENCE. |
|
Indicateur spécifié lorsque tous les fichiers de la file d’attente passent le case activée de signatures valides. SetupScanFileQueue informe l’utilisateur que l’opération nécessite des fichiers déjà présents sur la cible. Cet indicateur est ignoré si SPQ_SCAN_FILE_PRESENCE ou SPQ_SCAN_FILE_VALIDITY n’est pas spécifié. Cet indicateur ne peut pas être utilisé avec SPQ_SCAN_PRUNE_COPY_QUEUE ou SPQ_SCAN_PRUNE_DELREN. |
|
Combiné à SPQ_SCAN_FILE_PRESENCE, supprime les entrées présentes de la file d’attente de copie. En cas de combinaison avec SPQ_SCAN_FILE_VALIDITY, supprime les entrées signées de la file d’attente de copie. Disponible à partir de Windows 2000. Sur Windows XP uniquement, les fichiers qui sont également spécifiés dans les files d’attente de suppression ou de renommage ne sont pas taillés, sauf si SPQ_SCAN_PRUNE_DELREN est spécifié. |
|
Disponible à partir de Windows XP. Émet SPFILENOTIFY_QUEUESCAN_SIGNERINFO notification et transmet un pointeur vers une structure FILEPATHS_SIGNERINFO en tant que Param1. Recherche une signature valide dans chaque fichier et signale des informations de signature via la fonction de rappel. |
|
Combiné à SPQ_SCAN_FILE_PRESENCE ou SPQ_SCAN_FILE_VALIDITY, supprime les entrées de la file d’attente de suppression ou de renommage qui se trouvent également dans la file d’attente de copie. Lorsqu’il est combiné avec SPQ_SCAN_PRUNE_COPY_QUEUE, limite les fichiers supprimés de la file d’attente de copie aux fichiers qui ne figurent pas dans les files d’attente de suppression ou de renommage. Disponible à partir de Windows XP. |
[in] Window
Handle facultatif à la fenêtre pour posséder les boîtes de dialogue qui sont présentées. Ce paramètre n’est pas utilisé si le paramètre Flags ne contient pas de SPQ_SCAN_FILE_PRESENCE ou si Flags ne contient pas de SPQ_SCAN_INFORM_USER.
[in] CallbackRoutine
Pointeur facultatif vers une fonction de rappel FileCallback à appeler sur chaque nœud de la file d’attente de copie. Le code de notification passé à la fonction de rappel est SPFILENOTIFY_QUEUESCAN. Ce paramètre est obligatoire si Flags inclut SPQ_SCAN_USE_CALLBACK.
[in] CallbackContext
Pointeur facultatif vers un contexte qui contient des données définies par l’appelant passées à la routine de rappel pointée par CallbackRoutine.
[out] Result
Pointeur vers une variable qui reçoit le résultat de l’opération d’analyse.
Valeur retournée
La fonction retourne une valeur différente de zéro si tous les nœuds de la file d’attente ont été traités.
Si l’indicateur SPQ_SCAN_USE_CALLBACK a été défini, la valeur dans Result est 0. La routine de rappel spécifiée par CallbackRoutine reçoit la notification SPFILENOTIFY_QUEUESCAN. CallbackRoutine.Param1 spécifie un pointeur vers un tableau qui contient les informations de chemin d’accès cible. Le pointeur a été converti en entier non signé et doit être recastré en un tableau TCHAR d’éléments MAX_PATH avant qu’une routine de rappel puisse accéder aux informations. CallbackRoutine.Param2 est défini sur SPQ_DELAYED_COPY si le nœud de file d’attente actuel est en cours d’utilisation et ne peut pas être copié tant que le système n’est pas redémarré. Sinon, CallbackRoutine.Param2 prend la valeur 0.
Si SPQ_SCAN_USE_CALLBACK n’a pas été défini, Result indique si la file d’attente a réussi la présence ou la validité case activée comme indiqué dans le tableau suivant.
| Code de retour | Description |
|---|---|
|
La file d’attente a échoué le case activée ou elle a passé le case activée, mais SPQ_SCAN_INFORM_USER a été spécifié et l’utilisateur souhaite obtenir de nouvelles copies des fichiers. |
|
La file d’attente a passé le case activée et, si SPQ_SCAN_INFORM_USER a été spécifié, l’utilisateur a indiqué que la copie n’est pas obligatoire. La file d’attente de copie est vide et il n’y a aucun élément dans les files d’attente de suppression ou de renommage, de sorte que l’appelant peut ignorer la validation de la file d’attente. |
|
La file d’attente a passé le case activée et, si SPQ_SCAN_INFORM_USER a été spécifié, l’utilisateur a indiqué que la copie n’est pas obligatoire. La file d’attente de copie est vide, mais il existe des éléments sur les files d’attente de suppression ou de renommage, de sorte que l’appelant ne peut pas ignorer la validation de file d’attente. |
La fonction retourne zéro si une erreur s’est produite ou si la fonction de rappel a retourné une valeur différente de zéro. Si Result est différent de zéro, c’est la valeur retournée par la fonction de rappel qui a arrêté le traitement de la file d’attente. Si Result est égal à zéro, les informations d’erreur étendues peuvent être récupérées par un appel à GetLastError.
Remarques
Notes
L’en-tête setupapi.h définit SetupScanFileQueue 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 |