Funzione MsiFormatRecordA (msiquery.h)

  • Articolo

La funzione MsiFormatRecord formatta i dati e le proprietà dei campi di record usando una stringa di formato.

Sintassi

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

Parametri

[in] hInstall

Gestire l'installazione. Questa operazione può essere omessa, nel qual caso vengono elaborati solo i parametri del campo record e le proprietà non sono disponibili per la sostituzione.

[in] hRecord

Handle per il record da formattare. La stringa del modello deve essere archiviata nel campo record 0 seguito dai parametri di dati a cui si fa riferimento.

[out] szResultBuf

Puntatore al buffer che riceve la stringa formattata con terminazione Null. Non tentare di determinare le dimensioni del buffer passando un valore Null (value=0) per szResultBuf. È possibile ottenere le dimensioni del buffer passando una stringa vuota (ad esempio ""). La funzione restituisce quindi ERROR_MORE_DATA e pcchResultBuf contiene le dimensioni del buffer necessarie in TCHARs, senza includere il carattere null di terminazione. In caso di restituzione di ERROR_SUCCESS, pcchResultBuf contiene il numero di TCHARscritti nel buffer, senza includere il carattere Null di terminazione.

[in, out] pcchResultBuf

Puntatore alla variabile che specifica le dimensioni, in TCHARs, del buffer a cui punta la variabile szResultBuf. Quando la funzione restituisce ERROR_SUCCESS, questa variabile contiene le dimensioni dei dati copiati in szResultBuf, senza includere il carattere Null di terminazione. Se szResultBuf non è sufficientemente grande, la funzione restituisce ERROR_MORE_DATA e archivia le dimensioni necessarie, senza includere il carattere Null di terminazione, nella variabile a cui punta pcchResultBuf.

Valore restituito

La funzione MsiFormatRecord restituisce uno dei valori seguenti:

Commenti

La funzione MsiFormatRecord usa il processo di formato seguente.

I parametri che devono essere formattati sono racchiusi tra parentesi quadre [...]. Le parentesi quadre possono essere iterate perché le sostituzioni vengono risolte dall'interno.

Se una parte della stringa è racchiusa tra parentesi graffe { } e non contiene parentesi quadre, viene lasciata invariata, incluse le parentesi graffe.

Se una parte della stringa è racchiusa tra parentesi graffe { } e contiene uno o più nomi di proprietà e, se vengono trovate tutte le proprietà, il testo (con le sostituzioni risolte) viene visualizzato senza parentesi graffe. Se una delle proprietà non viene trovata, tutte le parentesi graffe e le parentesi graffe vengono rimosse.

Si noti che nel caso di azioni personalizzate di esecuzione posticipata , MsiFormatRecord supporta solo le proprietà CustomActionData e ProductCode . Per altre informazioni, vedere Ottenere informazioni sul contesto per azioni personalizzate di esecuzione posticipata.

I passaggi seguenti descrivono come formattare le stringhe usando la funzione MsiFormatRecord :

Per formattare le stringhe usando la funzione MsiFormatRecord

  1. I parametri numerici vengono sostituiti sostituendo il marcatore con il valore del campo record corrispondente, con valori mancanti o Null che non producono testo.
  2. La stringa risultante viene elaborata sostituendo i parametri non registrati con i valori corrispondenti, descritti di seguito.
    • Se viene rilevata una sottostringa del formato "[propertyname]", viene sostituita dal valore della proprietà.
    • Se viene trovata una sottostringa del formato "[%environmentvariable]", il valore della variabile di ambiente viene sostituito.
    • Se viene trovata una sottostringa del modulo " [#filekey]", viene sostituita dal percorso completo del file, con la chiave filekey del valore usata come chiave nella tabella File. Il valore di "[#filekey]" rimane vuoto e non viene sostituito da un percorso finché il programma di installazione non esegue l'azione CostInitialize, l'azione FileCost e l'azione CostFinalize. Il valore di "[#filekey]" dipende dallo stato di installazione del componente a cui appartiene il file. Se il componente viene eseguito dall'origine, il valore è il percorso del percorso di origine del file. Se il componente viene eseguito in locale, il valore è il percorso del percorso di destinazione del file dopo l'installazione. Se il componente è assente, il percorso è vuoto. Per altre informazioni sul controllo dello stato di installazione dei componenti, vedere Controllo dell'installazione di funzionalità, componenti, file.
    • Se viene trovata una sottostringa del formato "[$componentkey]", viene sostituita dalla directory di installazione del componente, con la chiave componentkey valore usata come chiave nella tabella Component. Il valore di "[$componentkey]" rimane vuoto e non viene sostituito da una directory finché il programma di installazione non esegue l'azione CostInitialize, l'azioneFileCost e l'azione CostFinalize. Il valore di "[$componentkey]" dipende dallo stato di installazione del componente. Se il componente viene eseguito dall'origine, il valore è la directory di origine del file. Se il componente viene eseguito in locale, il valore è la directory di destinazione dopo l'installazione. Se il componente è assente, il valore viene lasciato vuoto. Per altre informazioni sul controllo dello stato di installazione dei componenti, vedere Controllo dell'installazione di funzionalità, componenti, file.
    • Si noti che se un componente è già installato e non viene reinstallato, rimosso o spostato durante l'installazione corrente, lo stato dell'azione del componente è Null e pertanto la stringa "[$componentkey]" restituisce Null.
    • Se viene trovata una sottostringa del formato "[\c]", viene sostituita dal carattere senza ulteriori elaborazioni. Solo il primo carattere dopo la barra rovesciata viene mantenuto; tutto il resto viene rimosso.
Se viene restituito ERROR_MORE_DATA, il parametro che è un puntatore restituisce le dimensioni del buffer necessarie per contenere la stringa. Se ERROR_SUCCESS viene restituito, restituisce il numero di caratteri scritti nel buffer di stringhe. È pertanto possibile ottenere le dimensioni del buffer passando una stringa vuota (ad esempio "") per il parametro che specifica il buffer. Non tentare di determinare le dimensioni del buffer passando un valore Null (value=0).

Nota

L'intestazione msiquery.h definisce MsiFormatRecord come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

Requisiti

   
Client minimo supportato Windows Installer 5.0 in Windows Server 2012, Windows 8, Windows Server 2008 R2 o Windows 7. Windows Installer 4.0 o Windows Installer 4.5 in Windows Server 2008 o Windows Vista.
Piattaforma di destinazione Windows
Intestazione msiquery.h
Libreria Msi.lib
DLL Msi.dll

Vedi anche

Passaggio di Null come argomento delle funzioni di Windows Installer