MsiFormatRecordW 関数 (msiquery.h)

  • [アーティクル]

MsiFormatRecord 関数は、書式指定文字列を使用してレコード フィールドのデータとプロパティを書式設定します。

構文

UINT MsiFormatRecordW(
  [in]      MSIHANDLE hInstall,
  [in]      MSIHANDLE hRecord,
  [out]     LPWSTR    szResultBuf,
  [in, out] LPDWORD   pcchResultBuf
);

パラメーター

[in] hInstall

インストールを処理します。 これは省略できます。この場合、レコード フィールド パラメーターのみが処理され、プロパティは置換に使用できません。

[in] hRecord

書式設定するレコードを処理します。 テンプレート文字列は、レコード フィールド 0 の後に参照されるデータ パラメーターを格納する必要があります。

[out] szResultBuf

null で終わる書式設定された文字列を受け取るバッファーへのポインター。 szResultBuf に null (値=0) を渡してバッファーのサイズを判断しないでください。 バッファーのサイズを取得するには、空の文字列 (""など) を渡します。 次に、この関数は ERROR_MORE_DATA を返し、 pcchResultBuf には、終端の null 文字を含まない TCHARs の必要なバッファー サイズが含まれます。 ERROR_SUCCESSが返された場合、pcchResultBuf には、バッファーに書き込まれた TCHARの数が含まれ、終端の null 文字は含まれません。

[in, out] pcchResultBuf

変数 szResultBuf が指すバッファーのサイズを TCHARs で指定する変数へのポインター。 関数が ERROR_SUCCESSを返すと、この変数には 、szResultBuf にコピーされたデータのサイズが含まれます。終端の null 文字は含まれません。 szResultBuf が十分な大きさでない場合、関数は ERROR_MORE_DATAを返し、pcchResultBuf が指す変数に、終端の null 文字を含まない必要なサイズを格納します。

戻り値

MsiFormatRecord 関数は、次のいずれかの値を返します。

解説

MsiFormatRecord 関数は、次の形式プロセスを使用します。

書式設定するパラメーターは角かっこ [...] で囲まれます。代入は内側から解決されるため、角かっこを反復処理できます。

文字列の一部が中かっこ { } で囲まれており、角かっこが含まれない場合、中かっこを含め、変更されません。

文字列の一部が中かっこ { } で囲まれており、1 つ以上のプロパティ名が含まれている場合、すべてのプロパティが見つかった場合は、(解決された置換を含む) テキストが中かっこなしで表示されます。 いずれかのプロパティが見つからない場合は、中かっこと中かっこ自体のすべてのテキストが削除されます。

遅延実行のカスタム アクションの場合、 MsiFormatRecord では CustomActionData プロパティと ProductCode プロパティのみがサポートされます。 詳細については、「遅延実行カスタム アクションのコンテキスト情報の取得」を参照してください。

次の手順では、 MsiFormatRecord 関数を使用して文字列を書式設定する方法について説明します。

MsiFormatRecord 関数を使用して文字列を書式設定するには

  1. 数値パラメーターは、マーカーを対応するレコード フィールドの値に置き換えることで置き換え、テキストが生成されない値または null 値がない場合に置き換えます。
  2. 結果の文字列は、レコード以外のパラメーターを対応する値に置き換えることによって処理されます。次に説明します。
    • "[propertyname]" 形式の部分文字列が見つかった場合、プロパティの値に置き換えられます。
    • "[%environmentvariable]" 形式の部分文字列が見つかった場合、環境変数の値が置き換えられます。
    • フォームの部分文字列 "[#filekey]" が見つかった場合は、ファイルの完全なパスに置き換えられ、値 filekey が File テーブルのキーとして使用されます。 "[#filekey]" の値は空白のままであり、インストーラーが CostInitialize アクション、 FileCost アクション、および CostFinalize アクションを実行するまで、パスに置き換えされません。 "[#filekey]" の値は、ファイルが属するコンポーネントのインストール状態によって異なります。 コンポーネントがソースから実行されている場合、値はファイルのソースの場所へのパスです。 コンポーネントがローカルで実行されている場合、値はインストール後のファイルのターゲットの場所へのパスです。 コンポーネントが存在しない場合、パスは空白になります。 コンポーネントのインストール状態の確認の詳細については、「機能、コンポーネント、ファイルのインストールの確認」を参照してください。
    • "[$componentkey]" という形式の部分文字列が見つかった場合は、コンポーネントのインストール ディレクトリに置き換えられ、値 componentkey が Component テーブルのキーとして使用されます。 "[$componentkey]" の値は空白のままであり、インストーラーが CostInitialize アクション、 FileCost アクション、および CostFinalize アクションを実行するまで、ディレクトリに置き換えされません。 "[$componentkey]" の値は、コンポーネントのインストール状態によって異なります。 コンポーネントがソースから実行されている場合、値はファイルのソース ディレクトリです。 コンポーネントがローカルで実行されている場合、値はインストール後のターゲット ディレクトリです。 コンポーネントが存在しない場合、値は空白のままにされます。 コンポーネントのインストール状態の確認の詳細については、「機能、コンポーネント、ファイルのインストールの確認」を参照してください。
    • コンポーネントが既にインストールされていて、現在のインストール中に再インストール、削除、または移動されていない場合、コンポーネントのアクション状態は null であるため、文字列 "[$componentkey]" は Null と評価されることに注意してください。
    • "[\c]" 形式の部分文字列が見つかった場合、それ以上の処理を行わずに文字に置き換えられます。 円記号の後の最初の文字のみが保持されます。それ以外はすべて削除されます。
ERROR_MORE_DATAが返された場合、ポインターである パラメーターは、文字列を保持するために必要なバッファーのサイズを指定します。 ERROR_SUCCESSが返されると、文字列バッファーに書き込まれた文字数が返されます。 そのため、バッファーを指定するパラメーターに空の文字列 (""など) を渡すことで、バッファーのサイズを取得できます。 Null (値=0) を渡してバッファーのサイズを判断しないでください。

注意

msiquery.h ヘッダーは、MSIFormatRecord をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

   
サポートされている最小のクライアント Windows Server 2012、Windows 8、Windows Server 2008 R2、または Windows 7 の Windows インストーラー 5.0。 Windows Server 2008 または Windows Vista の Windows インストーラー 4.0 または Windows インストーラー 4.5。
対象プラットフォーム Windows
ヘッダー msiquery.h
Library Msi.lib
[DLL] Msi.dll

関連項目

Windows インストーラー関数の引数として Null を渡す