MsiFormatRecordA, fonction (msiquery.h)

Le MsiFormatRecord fonction met en forme les données de champ d’enregistrement et les propriétés à l’aide d’une chaîne de format.

Syntaxe

UINT MsiFormatRecordA(
  [in]      MSIHANDLE hInstall,
  [in]      MSIHANDLE hRecord,
  [out]     LPSTR     szResultBuf,
  [in, out] LPDWORD   pcchResultBuf
);

Paramètres

[in] hInstall

Gérez l’installation. Cela peut être omis, auquel cas seuls les paramètres de champ d’enregistrement sont traités et les propriétés ne sont pas disponibles pour la substitution.

[in] hRecord

Gérez l’enregistrement à mettre en forme. La chaîne de modèle doit être stockée dans le champ d’enregistrement 0 suivi des paramètres de données référencés.

[out] szResultBuf

Pointeur vers la mémoire tampon qui reçoit la chaîne mise en forme terminée par null. N’essayez pas de déterminer la taille de la mémoire tampon en transmettant une valeur Null (value=0) pour szResultBuf. Vous pouvez obtenir la taille de la mémoire tampon en passant une chaîne vide (par exemple « »). La fonction retourne ensuite ERROR_MORE_DATA et pcchResultBuf contient la taille de mémoire tampon requise dans TCHAR, sans inclure le caractère null de fin. Lors du retour de ERROR_SUCCESS, pcchResultBuf contient le nombre de TCHARécrites dans la mémoire tampon, sans inclure le caractère null de fin.

[in, out] pcchResultBuf

Pointeur vers la variable qui spécifie la taille, dans TCHARs, de la mémoire tampon pointée par la variable szResultBuf. Lorsque la fonction retourne ERROR_SUCCESS, cette variable contient la taille des données copiées dans szResultBuf, sans inclure le caractère null de fin. Si szResultBuf n’est pas suffisamment volumineux, la fonction retourne ERROR_MORE_DATA et stocke la taille requise, sans inclure le caractère null de fin, dans la variable pointée par pcchResultBuf.

Valeur de retour

La fonction MsiFormatRecord retourne l’une des valeurs suivantes :

Remarques

La fonction MsiFormatRecord utilise le processus de format suivant.

Les paramètres qui doivent être mis en forme sont placés entre crochets [...]. Les crochets peuvent être itérés, car les substitutions sont résolues de l’intérieur.

Si une partie de la chaîne est placée entre accolades { } et ne contient pas de crochets, elle est laissée inchangée, y compris les accolades.

Si une partie de la chaîne est placée entre accolades { } et contient un ou plusieurs noms de propriétés, et si toutes les propriétés sont trouvées, le texte (avec les substitutions résolues) s’affiche sans accolades. Si l’une des propriétés n’est pas trouvée, tout le texte dans les accolades et les accolades eux-mêmes sont supprimés.

Notez que dans le cas d’actions personnalisées d’exécution différées, MsiFormatRecord prend uniquement en charge les propriétés CustomActionData et ProductCode. Pour plus d’informations, consultez Obtention d’informations contextuelles pour les actions personnalisées d’exécution différées.

Les étapes suivantes décrivent comment mettre en forme des chaînes à l’aide de la fonction MsiFormatRecord :

Pour mettre en forme des chaînes à l’aide de la fonction MsiFormatRecord

1. Les paramètres numériques sont remplacés par le remplacement du marqueur par la valeur du champ d’enregistrement correspondant, par des valeurs manquantes ou null ne produisant aucun texte.
2. La chaîne résultante est traitée en remplaçant les paramètres de non-enregistrement par les valeurs correspondantes, décrites ensuite.
   • Si une sous-chaîne du formulaire « [propertyname] » est rencontrée, elle est remplacée par la valeur de la propriété.
   • Si une sous-chaîne de la forme « [%environmentvariable] » est trouvée, la valeur de la variable d’environnement est remplacée.
   • Si une sous-chaîne du formulaire " [#filekey] » est trouvée, elle est remplacée par le chemin d’accès complet du fichier, avec la valeur clé de fichier utilisée comme clé dans la table fichier . La valeur de « [#filekey] » reste vide et n’est pas remplacée par un chemin jusqu’à ce que le programme d’installation exécute l’action CostInitialize, action FileCostet Action CostFinalize. La valeur de « [#filekey] » dépend de l’état d’installation du composant auquel appartient le fichier. Si le composant est exécuté à partir de la source, la valeur est le chemin d’accès à l’emplacement source du fichier. Si le composant est exécuté localement, la valeur est le chemin d’accès à l’emplacement cible du fichier après l’installation. Si le composant est absent, le chemin d’accès est vide. Pour plus d’informations sur la vérification de l’état d’installation des composants, consultez Vérification de l’installation des fonctionnalités, composants, fichiers.
   • Si une sous-chaîne du formulaire « [$componentkey] » est trouvée, elle est remplacée par le répertoire d’installation du composant, avec la valeur clé de composant utilisée comme clé dans la table composant . La valeur de « [$componentkey] » reste vide et n’est pas remplacée par un répertoire tant que le programme d’installation n’exécute pas l’action CostInitialize, action FileCostet Action CostFinalize. La valeur de « [$componentkey] » dépend de l’état d’installation du composant. Si le composant est exécuté à partir de la source, la valeur est le répertoire source du fichier. Si le composant est exécuté localement, la valeur est le répertoire cible après l’installation. Si le composant est absent, la valeur est laissée vide. Pour plus d’informations sur la vérification de l’état d’installation des composants, consultez Vérification de l’installation des fonctionnalités, composants, fichiers.
   • Notez que si un composant est déjà installé et qu’il n’est pas réinstallé, supprimé ou déplacé pendant l’installation actuelle, l’état d’action du composant est Null et, par conséquent, la chaîne « [$componentkey] » prend la valeur Null.
   • Si une sous-chaîne du formulaire « [\c] » est trouvée, elle est remplacée par le caractère sans traitement supplémentaire. Seul le premier caractère après la barre oblique inverse est conservé ; tout le reste est supprimé.

Si ERROR_MORE_DATA est retourné, le paramètre qui est un pointeur donne la taille de la mémoire tampon requise pour contenir la chaîne. Si ERROR_SUCCESS est retourné, il donne le nombre de caractères écrits dans la mémoire tampon de chaîne. Par conséquent, vous pouvez obtenir la taille de la mémoire tampon en transmettant une chaîne vide (par exemple « ») pour le paramètre qui spécifie la mémoire tampon. N’essayez pas de déterminer la taille de la mémoire tampon en passant une valeur Null (value=0).

Exigences

Exigence	Valeur
client minimum 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.
plateforme cible	Windows
d’en-tête	msiquery.h
bibliothèque	Msi.lib
DLL	Msi.dll

Voir aussi

passage de null en tant qu’argument des fonctions Windows Installer