MsiFormatRecordA, fonction (msiquery.h)

  • Article

La fonction MsiFormatRecord met en forme les données et les propriétés des champs d’enregistrement à 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

Handle pour 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 vers 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 (valeur=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 les TCHAR, sans inclure le caractère null de fin. Au retour de ERROR_SUCCESS, pcchResultBuf contient le nombre de TCHARécrits 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, en 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 grand, 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 retournée

La fonction MsiFormatRecord retourne l’une des valeurs suivantes :

Notes

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 vers l’extérieur.

Si une partie de la chaîne est entourée d’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 entourée d’accolades { } et contient un ou plusieurs noms de propriété, 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 est introuvable, tout le texte dans les accolades et les accolades elles-mêmes sont supprimés.

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

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 marqueur par la valeur du champ d’enregistrement correspondant, avec des valeurs manquantes ou null ne produisant aucun texte.
  2. La chaîne résultante est traitée en remplaçant les paramètres non-enregistrement par les valeurs correspondantes, décrites ci-dessous.
    • Si une sous-chaîne de la forme « [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 de la forme « [#filekey] » est trouvée, elle est remplacée par le chemin d’accès complet du fichier, par la valeur filekey utilisée comme clé dans la table File. La valeur « [#filekey] » reste vide et n’est pas remplacée par un chemin tant que le programme d’installation n’exécute pas l’action CostInitialize, l’action FileCost et l’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 de l’emplacement source du fichier. Si le composant est exécuté localement, la valeur est le chemin de l’emplacement cible du fichier après l’installation. Si le composant est absent, le chemin 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, des composants, des fichiers.
    • Si une sous-chaîne de la forme « [$componentkey] » est trouvée, elle est remplacée par le répertoire d’installation du composant, par la valeur componentkey utilisée comme clé dans la table Component. La valeur « [$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, l’action FileCost et l’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, des composants, des fichiers.
    • Notez que si un composant est déjà installé et n’est pas en cours de réinstallation, de suppression ou de déplacement 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 de la forme « [\x] » 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 nécessaire 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 transmettant une valeur Null (valeur=0).

Notes

L’en-tête msiquery.h définit MsiFormatRecord 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.

Spécifications

   
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.
Plateforme cible Windows
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