msiFormatRecordA 函式 (msiquery.h)

  • 發行項

MsiFormatRecord 函式會使用格式字串來格式化記錄欄位資料和屬性。

語法

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

參數

[in] hInstall

安裝控制碼。 這可能會省略，在此情況下，只會處理記錄欄位參數，而且屬性無法替代。

[in] hRecord

要格式化之記錄的控制碼。 範本字串必須儲存在記錄欄位 0 中，後面接著參考的資料參數。

[out] szResultBuf

接收 Null 終止格式化字串之緩衝區的指標。 請勿嘗試藉由傳入 szResultBuf的 null (value=0) 來判斷緩衝區的大小。 您可以藉由傳入空字串 (來取得緩衝區的大小，例如 「」) 。 函式接著會 傳回ERROR_MORE_DATA ， 而 pcchResultBuf 包含 TCHAR中所需的緩衝區大小，不包括終止的 Null 字元。 在傳回 ERROR_SUCCESS時， pcchResultBuf 包含寫入緩衝區的 TCHAR數目，不包括終止的 Null 字元。

[in, out] pcchResultBuf

指定變數szResultBuf所指向緩衝區大小的變數指標，以TCHAR為單位。 當函式傳回 ERROR_SUCCESS時，此變數會包含複製到 szResultBuf的資料大小，不包括終止的 Null 字元。 如果 szResultBuf 不夠大，函式會傳回 ERROR_MORE_DATA 並儲存必要的大小，不包括 pcchResultBuf指向的變數中的終止 Null 字元。

傳回值

MsiFormatRecord 函式會傳回下列其中一個值：

備註

MsiFormatRecord函式會使用下列格式程式。

要 格式化 的參數會以方括弧 [...]括住。方括弧可以逐一查看，因為替代專案是從內部解析而來。

如果字串的一部分以大括弧 { } 括住，而且不包含方括弧，則會保持不變，包括大括弧。

如果字串的一部分以大括弧 { } 括住，且包含一或多個屬性名稱，而且如果找到所有屬性，則會顯示具有已解析替代專案的文字 (，) 沒有大括弧。 如果找不到任何屬性，則會移除大括弧和大括弧本身中的所有文字。

請注意，在延後執行自訂動作的情況下， MsiFormatRecord 僅支援 CustomActionData 和 ProductCode 屬性。 如需詳細資訊，請參閱 取得延後執行自訂動作的內容資訊。

下列步驟說明如何使用 MsiFormatRecord 函式來格式化字串：

使用 MsiFormatRecord 函式格式化字串

  1. 以對應的記錄欄位值取代標記，以取代數值參數，其中遺漏或 Null 值不會產生任何文字。
  2. 結果字串的處理方式是將非記錄參數取代為對應的值，如下所述。
    • 如果遇到 「[propertyname]」 格式的子字串，則會由 屬性的值取代。
    • 如果找到 「[%environmentvariable]」 格式的子字串，則會取代環境變數的值。
    • 如果找到表單 「[#filekey]」 的子字串，則會由檔案的完整路徑取代，並將它取代為File 資料表中索引鍵的值 filekey。 「[#filekey]」 的值會維持空白，而且在安裝程式執行 CostInitialize 巨集指令、 FileCost 宏指令和 CostFinalize 巨集指令之前，不會由路徑取代。 「[#filekey]」 的值取決於檔案所屬元件的安裝狀態。 如果元件是從來源執行，此值就是檔案來源位置的路徑。 如果元件是在本機執行，此值就是安裝後檔案的目標位置路徑。 如果元件不存在，則路徑為空白。 如需檢查元件安裝狀態的詳細資訊，請參閱 檢查功能安裝、元件、檔案。
    • 如果找到表單 「[$componentkey]」 的子字串，則會由元件的安裝目錄取代，並將做為元件資料表索引鍵的值 componentkey取代。 「[$componentkey]」 的值會維持空白，而且在安裝程式執行 CostInitialize 巨集指令、 FileCost 宏指令和 CostFinalize 巨集指令之前，不會由目錄取代。 「[$componentkey]」 的值取決於元件的安裝狀態。 如果元件是從來源執行，此值就是檔案的來原始目錄。 如果元件是在本機執行，則值會在安裝後成為目標目錄。 如果元件不存在，此值會保留空白。 如需檢查元件安裝狀態的詳細資訊，請參閱 檢查功能安裝、元件、檔案。
    • 請注意，如果已安裝元件，而且未在目前安裝期間重新安裝、移除或移動，元件的動作狀態會是 null，因此字串 「[$componentkey]」 會評估為 Null。
    • 如果找到 「[\c]」 格式的子字串，則會由字元取代，而不會進一步處理。 只保留反斜線之後的第一個字元;其他所有專案都會移除。
如果 傳回ERROR_MORE_DATA ，則為指標的參數會提供保存字串所需的緩衝區大小。 如果 傳回ERROR_SUCCESS ，它會提供寫入字串緩衝區的字元數。 因此，您可以傳入空字串 (，例如指定緩衝區之參數的 「」) ，以取得緩衝區的大小。 請勿嘗試藉由傳入 Null (value=0) 來判斷緩衝區的大小。

注意

msiquery.h 標頭會將 MsiFormatRecord 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。 如需詳細資訊，請參閱 函式原型的慣例。

需求

   
最低支援的用戶端 Windows Server 2012、Windows 8、Windows Server 2008 R2 或 Windows 7 上的 Windows Installer 5.0。 Windows Server 2008 或 Windows Vista 上的 Windows Installer 4.0 或 Windows Installer 4.5。
目標平台 Windows
標頭 msiquery.h
程式庫 Msi.lib
Dll Msi.dll

另請參閱

傳遞 Null 作為 Windows Installer 函式的引數