MsiProcessMessage, fonction (msiquery.h)

Article
08/25/2023

La fonction MsiProcessMessage envoie un enregistrement d’erreur au programme d’installation pour traitement.

Syntaxe

int MsiProcessMessage(
  [in] MSIHANDLE      hInstall,
  [in] INSTALLMESSAGE eMessageType,
  [in] MSIHANDLE      hRecord
);

Paramètres

[in] hInstall

Gérez l’installation fournie à une action personnalisée DLL ou obtenue via MsiOpenPackage, MsiOpenPackageEx ou MsiOpenProduct.

[in] eMessageType

Le paramètre eMessage doit être une valeur spécifiant l’un des types de messages suivants. Pour afficher une boîte de message avec des boutons poussoirs ou des icônes, utilisez les opérateurs OR pour ajouter INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING ou INSTALLMESSAGE_USER aux styles de boîte de message standard utilisés par les fonctions MessageBox et MessageBoxEx . Pour plus d’informations, consultez les remarques ci-dessous.

Valeur	Signification
INSTALLMESSAGE_FATALEXIT	Interruption prématurée, voire fatale, de la mémoire.
INSTALLMESSAGE_ERROR	Message d’erreur mis en forme, [1] est le numéro de message dans la table Error.
INSTALLMESSAGE_WARNING	Message d’avertissement mis en forme, [1] est le numéro de message dans la table Error.
INSTALLMESSAGE_USER	Message de demande de l’utilisateur, [1] est le numéro de message dans la table Error.
INSTALLMESSAGE_INFO	Message d’information pour le journal, ne doit pas être affiché.
INSTALLMESSAGE_FILESINUSE	Liste des fichiers actuellement utilisés qui doivent être fermés avant d’être remplacés.
INSTALLMESSAGE_RESOLVESOURCE	Demande de déterminer un emplacement source valide.
INSTALLMESSAGE_RMFILESINUSE	Liste des fichiers actuellement utilisés qui doivent être fermés avant d’être remplacés. Disponible à partir de Windows Installer version 4.0. Pour plus d’informations, consultez Utilisation du Gestionnaire de redémarrage avec une interface utilisateur externe.
INSTALLMESSAGE_OUTOFDISKSPACE	Message d'espace disque insuffisant.
INSTALLMESSAGE_ACTIONSTART	Progression : début de l’action, [1] nom de l’action, [2] description, [3] modèle pour les messages ACTIONDATA.
INSTALLMESSAGE_ACTIONDATA	Données d’action. Les champs d’enregistrement correspondent au modèle de message ACTIONSTART.
INSTALLMESSAGE_PROGRESS	Informations sur la barre de progression. Consultez la description des champs d’enregistrement ci-dessous.
INSTALLMESSAGE_COMMONDATA	Pour activer le bouton Annuler, définissez [1] sur 2 et [2] sur 1. Pour désactiver le bouton Annuler, définissez [1] sur 2 et [2] sur 0

[in] hRecord

Gérez vers un enregistrement contenant le format de message et les données.

Valeur retournée

Cette fonction retourne int.

Remarques

La fonction MsiProcessMessage effectue toutes les opérations de journalisation activées et diffère l’exécution. Vous pouvez activer la journalisation de manière sélective pour différents types de messages.

Pour INSTALLMESSAGE_FATALEXIT, INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING et INSTALLMESSAGE_USER messages, si le champ 0 n’est pas défini, le champ 1 doit être défini sur le code d’erreur correspondant au message d’erreur dans la table Error. Ensuite, le message est mis en forme à l’aide du modèle de la table Error avant de le transmettre au gestionnaire d’interface utilisateur pour affichage.

Champs d’enregistrement pour les messages de barre de progression

L’article suivant décrit les champs d’enregistrement lorsque eMessageType est défini sur INSTALLMESSAGE_PROGRESS. Le champ 1 spécifie le type du message de progression. La signification des autres champs dépend de la valeur de ce dernier. Les valeurs possibles pouvant être définies dans le champ 1 sont les suivantes.

Valeur du champ 1	Description du champ 1
0	Réinitialise la barre de progression et définit le nombre total de graduations attendues dans la barre.
1	Fournit des informations relatives aux messages de progression à envoyer par l'action en cours.
2	Augmente la barre de progression.
3	Permet à une action (telle que CustomAction) d’ajouter des graduations supplémentaires à la barre de progression.

La signification de la zone 2 dépend de la valeur de la zone 1 comme indiqué ci-après.

Valeur du champ 1	Description du champ 2
0	Nombre total de graduations attendues dans la barre de progression.
1	Nombre de graduations déplacées par la barre de progression pour chaque message ActionData envoyé par l’action actuelle. Ce champ est ignoré si le champ 3 a la valeur 0.
2	Nombre de crans effectués par la barre de progression.
3	Nombre de graduations à ajouter à la progression totale attendue.

La signification du champ 3 dépend de la valeur du champ 1 comme indiqué ci-après.

Valeur du champ 1	Valeur du champ 3	Description du champ 3
0	0	Progression de la barre vers l’avant (de gauche à droite)
	1	Progression de la barre vers l’arrière (de droite à gauche)
1	0	L’action actuelle envoie des messages ProgressReport explicites.
	1	Incrémentez la barre de progression du nombre de graduations spécifié dans le champ 2 chaque fois qu’un message ActionData est envoyé par l’action actuelle.
2	Inutilisé
3	Inutilisé

La signification du champ 4 dépend de la valeur du champ 1 comme indiqué ci-après.

Valeur du champ 1	Valeur du champ 4	Description du champ 4
0	0	L’exécution est en cours. Dans ce cas, l’UI peut calculer et afficher le temps restant.
	1	Création du script d’exécution. Dans ce cas, l’UI peut afficher un message demandant de patienter pendant que le programme d’installation termine la préparation de l’installation.
1	Inutilisé
2	Inutilisé
3	Inutilisé

Pour plus d’informations et un exemple de code, consultez Ajout d’actions personnalisées à progressBar.

Affichage des boîtes de message

Pour afficher une boîte de message avec des boutons ou des icônes, utilisez les opérateurs OR pour ajouter INSTALLMESSAGE_ERROR, INSTALLMESSAGE_WARNING ou INSTALLMESSAGE_USER avec les options de boîte de message utilisées par MessageBox et MessageBoxEx. Les options de bouton-pousseur disponibles sont MB_OK, MB_OKCANCEL, MB_ABORTRETRYIGNORE, MB_YESNOCANCEL, MB_YESNO et MB_RETRYCANCEL. Les options de bouton par défaut disponibles sont MB_DEFBUTTON1, MB_DEFBUTTON2 et MB_DEFBUTTON3. Les options d’icône disponibles sont MB_ICONERROR, MB_ICONQUESTION, MB_ICONWARNING et MB_ICONINFORMATION. Si aucune option d’icône n’est spécifiée, Windows Installer choisit un style d’icône par défaut en fonction du type de message.

Par exemple, l’appel suivant à MsiProcessMessage envoie un message INSTALLMESSAGE_ERROR avec l’icône MB_ICONWARNING et les boutons MB_ABORTRETRYCANCEL.

PMSIHANDLE hInstall;
PMSIHANDLE hRec;
MsiProcessMessage(hInstall, 
                  INSTALLMESSAGE(INSTALLMESSAGE_ERROR|MB_ABORTRETRYIGNORE|MB_ICONWARNING),
                  hRec);

Si une action personnalisée appelle MsiProcessMessage, l’action personnalisée doit être capable de gérer une annulation par l’utilisateur et doit retourner ERROR_INSTALL_USEREXIT.

Pour plus d’informations sur l’envoi de messages avec MsiProcessMessage, consultez Envoi de messages à Windows Installer à l’aide de MsiProcessMessage.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Installer 5.0 sur Windows Server 2012, Windows 8, Windows Server 2008 R2 ou Windows 7. Windows Installer 4.0 ou Windows Installer 4.5 sur Windows Server 2008 ou Windows Vista. Windows Installer sur Windows Server 2003 ou Windows XP
Plateforme cible	Windows
En-tête	msiquery.h
Bibliothèque	Msi.lib
DLL	Msi.dll

Voir aussi

Fonctions d’action du programme d’installation

Envoi de messages à Windows Installer à l’aide de MsiProcessMessage

Partager via