MsiProcessMessage を使用した Windows インストーラーへのメッセージの送信
MsiProcessMessage を使用して送信されるメッセージは、MsiSetExternalUI が呼び出された場合に INSTALLUI_HANDLER コールバック関数によって受信されるのと同じメッセージです。 それ以外の場合は、Windows インストーラーがこのメッセージを処理します。 詳細については、「Windows インストーラー メッセージの解析」を参照してください。
たとえば、MB_ICONWARNING アイコンと MB_ABORTRETRYCANCEL ボタンを含む INSTALLMESSAGE_ERROR メッセージを送信するには、次のようにします。
PMSIHANDLE hInstall;
PMSIHANDLE hRec;
MsiProcessMessage(hInstall, INSTALLMESSAGE(INSTALLMESSAGE_ERROR|MB_ABORTRETRYIGNORE|MB_ICONWARNING), hRec);
ここで、hInstall は (カスタム アクションに提供された) インストールへのハンドルか、あるいは MsiOpenProduct または MsiOpenPackage の hProduct ハンドルであり、hRec は書式設定するエラー情報が含まれているレコードです。 書式設定が実行される方法については、MsiFormatRecord に関するページを参照してください。
既定では、ボタンの種類やアイコンの種類を指定せずに INSTALLMESSAGE_ERROR または INSTALLMESSAGE_FATALEXIT メッセージが送信される場合は、MB_OK、アイコンなし、MB_DEFBUTTON1 が使用されます。
Windows インストーラーでは、MB_ABORTRETRYIGNORE ボタン仕様で MessageBox を表示するときに ABORT ボタンに "中止" という文字列のラベルは付けず、代わりに "キャンセル" という文字列のラベルを付けます。 すべてのエラー メッセージで "中止" という単語の使用を避け、代わりに "キャンセル" という単語を使用します。
MsiProcessMessage 関数の hRecord パラメーターは、MsiProcessMessage に送信されるメッセージの種類によって異なります。 次の一覧は、メッセージの種類に関連するレコードの要件を詳細に示しています。
INSTALLMESSAGE_FATALEXIT
INSTALLMESSAGE_INFO
INSTALLMESSAGE_OUTOFDISKSPACE
| フィールド | 説明 |
|---|---|
| 0 | 結果として得られる文字列の書式設定のためのテンプレート。 詳細については、MsiFormatRecord に関するページを参照してください。 レコードのフィールドは、フィールド 1 の場合は [1]、フィールド 2 の場合は [2] などを使用して参照されます。 |
| 1 から n | 以降のすべてのフィールドは、フィールド 0 のテンプレートによって参照されるフィールドに直接関連付けられます。 |
フィールド 0 が null である場合、UI ハンドラーによって受信される文字列は "1: [フィールド 1 のデータ] 2: [フィールド 2 のデータ]" のように書式設定されます。つまり、レコードの各フィールドの文字列には、フィールド番号の後に、そのフィールドに格納されているデータが含まれています。
MsiProcessMessage からの情報メッセージは、MsiEnableLog、"/l" のコマンド ライン オプション、またはログ ポリシーで "I" または INSTALLLOGMODE_INFO が指定されている場合にログに記録されます。
INSTALLMESSAGE_ERROR
INSTALLMESSAGE_WARNING
INSTALLMESSAGE_USER
Error テーブルのメッセージを使用する場合。
| フィールド | 説明 |
|---|---|
| 0 | null である必要があります。 |
| 1 | Error テーブル内のメッセージ番号。 |
| 2 から n | Error テーブル内の指定されたメッセージに関連しています。 |
次に例を示します。
| フィールド | Type | データ |
|---|---|---|
| 0 | string | null |
| 1 | INT | 1304 |
| 2 | string | Myfile.txt |
UI ハンドラーから受信される結果のメッセージは次のとおりです。
エラー 1304。 ファイル Myfile.txt への書き込み中にエラーが発生しました。 そのディレクトリにアクセスできることを確認してください。
フィールド 0 が null でない場合は、Error テーブルからのメッセージがオーバーライドされます。 代わりに、フィールド 0 のテンプレートによってメッセージの形式が決定されます。
このメッセージではまた、前に説明したメッセージで使用されるボタン (既定のボタンを含む) やアイコンを指定することもできます。 ボタンとアイコンの種類は、INSTALLUI_HANDLER に関するページに記載されています。
INSTALLMESSAGE_COMMONDATA
このメッセージは、進行状況ダイアログ ボックス内の [キャンセル] ボタンを有効または無効にするために送信されます。
| フィールド | 説明 |
|---|---|
| 0 | 未使用。 |
| 1 | 2 が [キャンセル] ボタンを示します。 |
| 2 | 1 の値は、[キャンセル] ボタンを表示する必要があることを示します。 0 の値は、[キャンセル] ボタンを非表示にする必要があることを示します。 |
たとえば、[キャンセル] ボタンを無効または非表示にするには、レコードを次のようにします。
| フィールド | Type | データ |
|---|---|---|
| 0 | string | null |
| 1 | INT | 2 |
| 2 | INT | 0 |
INSTALLMESSAGE_ACTIONSTART
INSTALLMESSAGE_ACTIONDATA
INSTALLMESSAGE_ACTIONSTART レコードによって、ActionData レコードの形式が決定されます。
| フィールド | 説明 |
|---|---|
| 0 | null |
| 1 | アクション名。 このフィールド内の名前は null 以外である必要があります。 |
| 2 | アクションの説明。 |
| 3 | アクション テンプレート。 これは、メッセージがこのテンプレートに従って書式設定されている ActionData に使用されます。 |
アクション テンプレートのメッセージでフィールド 0 を参照しないでください。
INSTALLMESSAGE_ACTIONDATA レコードは、次のように書式設定されます。
| フィールド | 説明 |
|---|---|
| 0 | null |
| 1 から n | ActionText テーブルで指定されている対応する INSTALLMESSAGE_ACTIONSTART メッセージまたはテンプレートのフィールド 3 に依存します。 |
たとえば、次の INSTALLMESSAGE_ACTIONSTART レコードを考えてみます。
| フィールド | Type | データ |
|---|---|---|
| 0 | string | null |
| 1 | string | MyAction |
| 2 | string | これは "MyAction" の説明です。 |
| 3 | string | MyAction テンプレート: フィールド 1 のデータは [1]。 フィールド 2 のデータは [2]。 |
INSTALLMESSAGE_ACTIONSTART (フィールド 3) のテンプレートは、フィールド 1 と 2 を参照します。INSTALLMESSAGE_ACTIONDATA レコードには、保証されたデータを含む 2 つのフィールドが必要です。 これらのフィールドは、文字列または整数フィールドのどちらでもかまいません。
INSTALLMESSAGE_ACTIONDATA レコード。
| フィールド | Type | データ |
|---|---|---|
| 0 | string | null |
| 1 | INT | 2 |
| 2 | string | MyAction の ActionData |
INSTALLMESSAGE_FILESINUSE
FILESINUSE レコードは、可変長のレコードです。
| フィールド | 説明 |
|---|---|
| 0 | このフィールドには null を指定できます。 基本的な UI を使用するインストールの場合、このフィールドでは、FilesInUse ダイアログの ListBox コントロールに表示する静的テキストを指定できます。 完全な UI を使用するインストールの場合は、テキストがカスタム FilesInUse ダイアログ ボックスの作成によって指定されるため、このフィールドは効果がありません。 |
| 1 | 使用中のファイルの名前。 |
| 2 | このフィールドは、使用中のファイルを保持しているプロセスを識別します。Windows インストーラー バージョン 4.0: そのプロセスのプロセス ID (PID)、またはそのプロセスのウィンドウのタイトル。 Windows インストーラー バージョン 3.1 以前: このフィールドは、そのプロセスのプロセス ID (PID) である必要があります。 |
たとえば、2 つの使用中のファイル red.exe と blue.exe を示す FilesInUse メッセージを送信するには、レコードに 4 つのフィールドに加えてフィールド 0 を含めます。 レコードの形式は、次の表に示すようになります。 この例には、Windows インストーラー バージョン 4.0 が必要です。
Windows インストーラー バージョン 3.1 以前: 次の例のフィールド 2 と 4 には、使用中の red.exe と blue.exe を保持しているプロセスの PID が含まれている必要があります。
| フィールド | 説明 |
|---|---|
| 0 | null |
| 1 | Red.exe |
| 2 | 赤いウィンドウ タイトル |
| 3 | Blue.exe |
| 4 | 青いウィンドウ タイトル |
Note
Windows インストーラー バージョン 4.0 では、サービスから渡された PID にウィンドウ タイトル (システム トレイ アプリケーションなど) がない場合、ファイルは表示されず、詳細ログには次のメッセージが含まれています。
File In Use: -<FileName>- Window could not be found. Process ID: <PID>
No window with title could be found for FilesInUse
INSTALLMESSAGE_RESOLVESOURCE
INSTALLMESSAGE_RESOLVESOURCE レコードには 7 つのフィールドがあります。 INSTALLMESSAGE_RESOLVESOURCE を正しく機能させるために、外部 UI ハンドラーは INSTALLMESSAGE_RESOLVESOURCE メッセージを処理しない可能性があります。 Windows インストーラーが INSTALLMESSAGE_RESOLVESOURCE メッセージを処理する必要があります。 つまり、外部 UI ハンドラーは、INSTALLMESSAGE_RESOLVESOURCE メッセージをフィルター処理したときに "アクションが実行されない" ことを示す 0 を返します。 RESOLVESOURCE メッセージの送信を回避することがベスト プラクティスになります。
| フィールド | 説明 |
|---|---|
| 0 | null |
| 1 | null |
| 2 | パッケージ名。 |
| 3 | 製品コード。 |
| 4 | 相対パス (既知の場合)。null を指定できます。 |
| 5 | 0 |
| 6 | パッケージ コードを検証するかどうか。 "1" の値は、パッケージ コードを検証する必要があることを示します。 "0" の値は、パッケージを検証するべきではないことを示します。 |
| 7 | メディア テーブルの必要なディスク。 "0" の値は、どのディスクも許容されることを示します。 |