MsiFormatRecordA-Funktion (msiquery.h)

  • Artikel

Die MsiFormatRecord-Funktion formatiert Datensatzfelddaten und Eigenschaften mithilfe einer Formatzeichenfolge.

Syntax

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

Parameter

[in] hInstall

Handle für die Installation. Dies kann weggelassen werden. In diesem Fall werden nur die Datensatzfeldparameter verarbeitet, und Die Eigenschaften stehen nicht zur Ersetzung zur Verfügung.

[in] hRecord

Handle für den zu formatierenden Datensatz. Die Vorlagenzeichenfolge muss im Datensatzfeld 0 gespeichert werden, gefolgt von Datenparametern, auf die verwiesen wird.

[out] szResultBuf

Zeiger auf den Puffer, der die mit NULL beendete formatierte Zeichenfolge empfängt. Versuchen Sie nicht, die Größe des Puffers zu bestimmen, indem Sie null (value=0) für szResultBuf übergeben. Sie können die Größe des Puffers abrufen, indem Sie eine leere Zeichenfolge übergeben (z. B. ""). Die Funktion gibt dann ERROR_MORE_DATA zurück, und pcchResultBuf enthält die erforderliche Puffergröße in TCHARs, ohne das abschließende NULL-Zeichen. Bei Rückgabe von ERROR_SUCCESS enthält pcchResultBuf die Anzahl der TCHAR-Werte, die in den Puffer geschrieben werden, ohne das abschließende NULL-Zeichen.

[in, out] pcchResultBuf

Zeiger auf die Variable, die die Größe des Puffers in TCHARs angibt, auf den die Variable szResultBuf verweist. Wenn die Funktion ERROR_SUCCESS zurückgibt, enthält diese Variable die Größe der in szResultBuf kopierten Daten, ohne das abschließende NULL-Zeichen. Wenn szResultBuf nicht groß genug ist, gibt die Funktion ERROR_MORE_DATA zurück und speichert die erforderliche Größe (ohne das abschließende NULL-Zeichen) in der Variablen, auf die von pcchResultBuf verwiesen wird.

Rückgabewert

Die MsiFormatRecord-Funktion gibt einen der folgenden Werte zurück:

Hinweise

Die MsiFormatRecord-Funktion verwendet den folgenden Formatprozess.

Parameter, die formatiert werden sollen, werden in eckige Klammern eingeschlossen [...]. Die eckigen Klammern können durchlaufen werden, da die Ersetzungen von innen nach außen aufgelöst werden.

Wenn ein Teil der Zeichenfolge in geschweifte Klammern { } eingeschlossen ist und keine eckigen Klammern enthält, bleibt dieser Teil einschließlich der geschweiften Klammern unverändert.

Wenn ein Teil der Zeichenfolge in geschweifte Klammern { } eingeschlossen ist und einen oder mehrere Eigenschaftsnamen enthält, und wenn alle Eigenschaften gefunden werden, wird der Text (mit den aufgelösten Ersetzungen) ohne die geschweiften Klammern angezeigt. Wenn keine der Eigenschaften gefunden wird, werden der gesamte Text in den geschweiften Klammern und den geschweiften Klammern selbst entfernt.

Beachten Sie, dass MsiFormatRecord bei benutzerdefinierten Aktionen für verzögerte Ausführung nur die Eigenschaften CustomActionData und ProductCode unterstützt. Weitere Informationen finden Sie unter Abrufen von Kontextinformationen für verzögert auszuführende benutzerdefinierte Aktionen.

In den folgenden Schritten wird beschrieben, wie Zeichenfolgen mithilfe der MsiFormatRecord-Funktion formatiert werden :

So formatieren Sie Zeichenfolgen mit der MsiFormatRecord-Funktion

  1. Die numerischen Parameter werden ersetzt, indem der Marker durch den Wert des entsprechenden Datensatzfelds durch fehlende oder NULL-Werte ersetzt wird, die keinen Text erzeugen.
  2. Die resultierende Zeichenfolge wird verarbeitet, indem die Parameter ohne Datensatz durch die entsprechenden Werte ersetzt werden, die als Nächstes beschrieben werden.
    • Wird eine Teilzeichenfolge im Format „[propertyname]“ gefunden, wird diese durch den Wert der Eigenschaft ersetzt.
    • Wird eine Teilzeichenfolge im Format „[%environmentvariable]“ gefunden, wird der Wert der Umgebungsvariablen eingesetzt.
    • Wenn eine Teilzeichenfolge des Formulars "[#filekey]" gefunden wird, wird sie durch den vollständigen Pfad der Datei ersetzt, wobei der Wert filekey als Schlüssel in der Dateitabelle verwendet wird. Der Wert von "[#filekey]" bleibt leer und wird erst durch einen Pfad ersetzt, wenn das Installationsprogramm die Aktionen CostInitialize, FileCost und CostFinalize ausführt. Der Wert von "[#filekey]" hängt vom Installationsstatus der Komponente ab, zu der die Datei gehört. Wenn die Komponente von der Quelle aus ausgeführt wird, entspricht der Wert dem Pfad zum Quellspeicherort der Datei. Wenn die Komponente lokal ausgeführt wird, entspricht der Wert dem Pfad zum Zielspeicherort der Datei nach der Installation. Ist die Komponente nicht vorhanden, ist der Pfad leer. Weitere Informationen zum Überprüfen des Installationszustands von Komponenten finden Sie unter Überprüfen der Installation von Features, Komponenten und Dateien.
    • Wenn eine Teilzeichenfolge im Format "[$componentkey]" gefunden wird, wird sie durch das Installationsverzeichnis der Komponente ersetzt, wobei der Wert componentkey als Schlüssel in der Tabelle Component verwendet wird. Der Wert von "[$componentkey]" bleibt leer und wird erst durch ein Verzeichnis ersetzt, wenn das Installationsprogramm die Aktionen CostInitialize, FileCost und CostFinalize ausführt. Der Wert von "[$componentkey]" hängt vom Installationsstatus der Komponente ab. Wenn die Komponente von der Quelle aus ausgeführt wird, entspricht der Wert dem Quellverzeichnis der Datei. Wenn die Komponente lokal ausgeführt wird, entspricht der Wert dem Zielverzeichnis nach der Installation. Wenn die Komponente nicht vorhanden ist, bleibt der Wert leer. Weitere Informationen zum Überprüfen des Installationszustands von Komponenten finden Sie unter Überprüfen der Installation von Features, Komponenten und Dateien.
    • Beachten Sie, dass, wenn eine Komponente bereits installiert ist und während der aktuellen Installation nicht neu installiert, entfernt oder verschoben wird, der Aktionsstatus der Komponente NULL ist und daher die Zeichenfolge "[$componentkey]" als Null ausgewertet wird.
    • Wird eine Teilzeichenfolge der Form „[\c]“ gefunden, wird diese ohne weitere Verarbeitung durch das Zeichen ersetzt. Nur das erste Zeichen nach dem umgekehrten Schrägstrich wird beibehalten, alle übrigen werden entfernt.
Wenn ERROR_MORE_DATA zurückgegeben wird, gibt der Parameter, bei dem es sich um einen Zeiger handelt, die Größe des Puffers an, der zum Halten der Zeichenfolge erforderlich ist. Wenn ERROR_SUCCESS zurückgegeben wird, wird die Anzahl der Zeichen angegeben, die in den Zeichenfolgenpuffer geschrieben werden. Daher können Sie die Größe des Puffers abrufen, indem Sie eine leere Zeichenfolge (z. B. "") für den Parameter übergeben, der den Puffer angibt. Versuchen Sie nicht, die Größe des Puffers zu bestimmen, indem Sie einen Nullwert (wert=0) übergeben.

Hinweis

Der msiquery.h-Header definiert MsiFormatRecord als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows Installer 5.0 unter Windows Server 2012, Windows 8, Windows Server 2008 R2 oder Windows 7. Windows Installer 4.0 oder Windows Installer 4.5 unter Windows Server 2008 oder Windows Vista.
Zielplattform Windows
Kopfzeile msiquery.h
Bibliothek Msi.lib
DLL Msi.dll

Weitere Informationen

Übergeben von NULL als Argument von Windows Installer Functions