ホーム › System.ApplicationInstallationAndServicing › IMsmMerge

IMsmMerge

COMIDispatch (デュアル)

📘 Microsoft Learn (日本語) · English

✅ IDispatch を実装(デュアルインターフェース)。HSP では comobj 経由でメソッド名による遅延バインド呼び出しができます(vtableインデックス不要)。

IID0adda82e-2c26-11d2-ad65-00a0c9af11a6継承元IDispatch呼び出し名前(IDispatch) または vtbl自前メソッド開始 vtbl7

公式ドキュメント

IMsmMerge インターフェイスと IMsmMerge2 インターフェイスは、Merge オブジェクトへのインターフェイスを提供します。

メソッド 13

vtbl = vtable インデックス(0始まり)。IDispatch 実装のため HSP ではメソッド名でも呼べます(上記)。低レベルの index 呼び出し用に vtbl も掲載。0〜2 は IUnknown。

vtbl 7 HRESULT OpenDatabase(LPWSTR Path)

OpenDatabase メソッドは、指定したパスにある、モジュールとマージする Windows Installer インストールデータベースを開きます。詳細については、Merge オブジェクトの OpenDatabase メソッドを参照してください。

Path

LPWSTR

開くデータベースへのパス。

戻り値

このメソッドは、次のいずれかの値を返します。

値	意味
E_FAIL	データベースを開く際にエラーが発生しました。
S_OK	関数が成功しました。

vtbl 8 HRESULT OpenModule(LPWSTR Path, SHORT Language)

OpenModule メソッドは、Windows Installer マージモジュールを読み取り専用モードで開きます。モジュールは、インストールデータベースとマージする前に開いておく必要があります。詳細については、Merge オブジェクトの OpenModule メソッドを参照してください。

Path	LPWSTR	in	マージモジュールを指す完全修飾ファイル名。BSTR の代わりに LPCWSTR を使用できます。
Language	SHORT	in	言語識別子 (LANGID)。

戻り値

OpenModule 関数は、次の値を返します。

値	意味
E_ABORT	指定されたファイルは Windows Installer データベースですが、マージモジュールではありません ( ModuleSignature テーブルがありません)。
ERROR_INSTALL_LANGUAGE_UNSUPPORTED as HRESULT	この言語はモジュールでサポートされていません。
ERROR_INSTALL_TRANSFORM_FAILURE as HRESULT	この言語はモジュールでサポートされていますが、変換の適用時にエラーが発生しました。
ERROR_OPEN_FAILED as HRESULT	このファイルを Windows Installer データベースとして開けませんでした。
ERROR_TOO_MANY_OPEN_FILES as HRESULT	既にモジュールが開かれています。まず現在のモジュールを閉じてください。
S_OK	関数が成功しました。

解説(Remarks)

この関数は、マージモジュールを読み取り専用モード (MSIDBOPEN_READONLY) で開き、 CloseModule 関数が呼び出されるまで、他のプログラムがマージモジュールへ書き込むことを禁止します。マージモジュールは、マージする前に開いておく必要があります。

インストーラーは、Language で指定された言語、またはそれより一般的な言語でモジュールを開こうとします。たとえば、Language の値に 1033 が指定された場合、既定の言語が 1033、9、または 0 のモジュールは、その既定の言語で開かれます。Language の値が 9 の場合、既定の言語が 9 または 0 のモジュールが開かれます。モジュールの既定の言語が指定された要件を満たさない場合、モジュールを要求された言語へ変換しようとします。それが失敗した場合、インストーラーは、言語ニュートラルに至るまで、モジュールをより一般的な言語へ順次変換しようとします。いずれの変換も成功しない場合、モジュールを開くことができません。この場合、msmErrorLanguageUnsupported 型のエラーがエラーリストに追加され、関数は ERROR_INSTALL_LANGUAGE_UNSUPPORTED as HRESULT を返します。

モジュールを目的の言語に変換する際にエラーが発生した場合、msmErrorLanguageFailed 型のエラーが作成され、関数は ERROR_INSTALL_TRANSFORM_FAILURE as HRESULT を返します。

詳細については、 Error オブジェクトの Type プロパティを参照してください。

マージモジュールを開くと、まだ取得されていないエラーはすべてクリアされます。

vtbl 9 HRESULT CloseDatabase(VARIANT_BOOL Commit)

CloseDatabase メソッドは、現在開いている Windows Installer データベースを閉じます。詳細については、Merge オブジェクトの CloseDatabase メソッドを参照してください。

Commit

VARIANT_BOOL

変更を保存する場合は TRUE、そうでない場合は FALSE。

戻り値

CloseDatabase 関数は、次の値を返します。

値	意味
E_FAIL	データベースを閉じる際にエラーが発生しました。 IMsmMerge インターフェイスまたは IMsmMerge2 インターフェイスの状態は、現在、未定義の状態になっています。
S_FALSE	開いているデータベースがありませんでした。
S_OK	関数が成功しました。
STG_E_CANTSAVE as HRESULT	データベースを保存できません。bCommit が FALSE の場合、このエラーは生成されません。

解説(Remarks)

この関数は、現在開いているデータベースを閉じます。データベースを閉じると、すべての依存関係情報がクリアされますが、まだ取得されていないエラーには影響しません。

vtbl 10 HRESULT CloseModule()

CloseModule メソッドは、現在開いている Windows Installer マージモジュールを閉じます。詳細については、Merge オブジェクトの CloseModule メソッドを参照してください。

戻り値

CloseModule 関数は、次の値を返します。

値	意味
E_FAIL	モジュールを閉じる際にエラーが発生しました。 IMsmMerge インターフェイスまたは IMsmMerge2 インターフェイスの状態は、現在、未定義です。
S_FALSE	開いているモジュールがありませんでした。
S_OK	関数が成功しました。

解説(Remarks)

マージモジュールを閉じても、まだ取得されていないエラーには影響しません。

vtbl 11 HRESULT OpenLog(LPWSTR Path)

OpenLog メソッドは、進行状況メッセージとエラーメッセージを受け取るログファイルを開きます。

Path

LPWSTR

開くまたは作成するファイルを指す完全修飾ファイル名。BSTR の代わりに LPCWSTR を使用できます。

戻り値

このメソッドは、次のいずれかの値を返します。

値	意味
ERROR_TOO_MANY_OPEN_FILES as HRESULT	既にログファイルが開かれています。
ERROR_OPEN_FAILED as HRESULT	ファイルを開くまたは作成できませんでした。
S_OK	関数が成功しました。

解説(Remarks)

この関数は、進行状況メッセージとエラーメッセージを受け取るためのログファイルを開きます。ログファイルが既に存在する場合、新しいメッセージがログに追加されます。ログファイルが存在しない場合は作成されます。

クライアントは、Log を使用して独自のメッセージをこのログファイルへ送信できます。

vtbl 12 HRESULT CloseLog()

CloseLog メソッドは、現在のログを閉じます。詳細については、Merge オブジェクトの CloseLog メソッドを参照してください。

戻り値

このメソッドは、次のいずれかの値を返します。

値	意味
E_FAIL	ログファイルを閉じる際にエラーが発生しました。
S_FALSE	開いているログファイルがありませんでした。
S_OK	関数が成功しました。

vtbl 13 HRESULT Log(LPWSTR Message)

Log メソッドは、現在開いているログファイルにテキスト文字列を書き込みます。詳細については、Merge オブジェクトの Log メソッドを参照してください。

Message

LPWSTR

表示するテキスト文字列。BSTR の代わりに LPCWSTR を使用できます。

戻り値

このメソッドは、次のいずれかの値を返します。

値	意味
E_FAIL	ログファイルへの書き込み時にエラーが発生しました。
E_INVALIDARG	引数が無効です。
S_FALSE	開いているログファイルがありません。
S_OK	関数が成功しました。

vtbl 14 HRESULT get_Errors(IMsmErrors** Errors)

get_Errors メソッドは、Merge オブジェクトの Errors プロパティを取得します。これにより、現在のエラーのコレクションが取得されます。

Errors

IMsmErrors**

out

IMsmErrors インターフェイスへの別のポインターを格納するメモリ位置へのポインター。

戻り値

このメソッドは、次のいずれかの値を返します。

値	意味
E_INVALIDARG	Errors ポインターが NULL です。
E_OUTOFMEMORY	システムのメモリが不足しています。
S_OK	関数が成功しました。

解説(Remarks)

この取得は非破壊的です。つまり、このメソッドを繰り返し呼び出すことで、エラーコレクションの複数のインスタンスを取得できます。

エラーが発生した場合、Errors が指すメモリ位置は NULL に設定されます。

この関数が返すインターフェイスの解放は、クライアントが行う必要があります。

vtbl 15 HRESULT get_Dependencies(IMsmDependencies** Dependencies)

get_Dependencies メソッドは、Merge オブジェクトの Dependencies プロパティを取得します。

Dependencies

IMsmDependencies**

out

現在のデータベースの未解決の依存関係のコレクションへのポインターが格納されるメモリ位置へのポインター。エラーが発生した場合、Dependencies が指すメモリ位置は null に設定されます。

戻り値

                <b>get_Dependencies</b> 関数は、次の値を返します。

値	意味
E_FAIL	開いているデータベースがありませんでした。
E_INVALIDARG	Dependencies ポインターが null です。
E_OUTOFMEMORY	システムのメモリが不足しました。
E_UNEXPECTED	内部エラーのため、依存関係を検証できません。
S_OK	関数が成功しました。

解説(Remarks)

依存関係情報を取得するために、モジュールを開いておく必要はありません。この関数が返すインターフェイスの解放は、クライアントが行う必要があります。

vtbl 16 HRESULT Merge(LPWSTR Feature, LPWSTR RedirectDir)

Merge メソッドは、現在のデータベースと現在のモジュールのマージを実行します。

Feature	LPWSTR	in	データベース内の機能の名前。BSTR の代わりに LPCWSTR を使用できます。
RedirectDir	LPWSTR	in	データベースの Directory テーブル内のエントリのキー。BSTR の代わりに LPCWSTR を使用できます。このパラメーターには null または空の文字列を指定できます。

戻り値

Merge 関数は、次の値を返します。

値	意味
E_FAIL	マージが致命的に失敗しました。これは動作上のエラーを示すものであり、マージ失敗時の通常のエラー戻り値ではありません。
S_FALSE	関数は成功しましたが、エラーが発生しており、マージ自体が有効でない可能性があります。
E_INVALIDARG	引数のいずれかが無効です。
E_OUTOFMEMORY	システムのメモリが不足し、操作を完了できませんでした。
S_OK	関数が成功しました。

解説(Remarks)

この関数は、現在のデータベースと現在のモジュールのマージを実行します。モジュールのディレクトリツリーのルートは、RedirectDir で指定された場所にリダイレクトされます。除外を含むマージの競合が発生した場合、それらは後で取得できるようエラー列挙子に格納されますが、マージが失敗する原因にはなりません。エラーは get_Errors 関数を使用して取得できます。エラーと情報メッセージは現在のログファイルに記録されます。

Merge 関数は、モジュール内のすべての機能参照を取得し、モジュールデータベース内のすべての null GUID の出現箇所を、その機能参照で置き換えることに注意してください。詳細については、 Referencing Features in Merge Modules を参照してください。

マージが完了すると、モジュール内のコンポーネントは Feature で識別される機能に関連付けられます。この機能は既に存在している必要があり、新たに作成されることはありません。

モジュールは、 Connect 関数を使用して追加の機能に関連付けることができます。 Connect 関数を呼び出しても、機能とコンポーネントの関連付けが作成されるだけであることに注意してください。既にデータベースにマージされている行は変更されません。

データベースに加えた変更は、 CloseDatabase 関数を bCommit に TRUE を設定して呼び出さない限り、ディスクに保存されません。

vtbl 17 HRESULT Connect(LPWSTR Feature)

Connect メソッドは、データベースに既にマージされた、またはこれからマージされるモジュールを、追加の機能に接続します。詳細については、Merge オブジェクトの Connect メソッドを参照してください。

Feature

LPWSTR

データベース内の機能の名前。BSTR の代わりに LPCWSTR を使用できます。

戻り値

このメソッドは、次のいずれかの値を返します。

値	意味
E_INVALIDARG	引数のいずれかが無効です。
E_FAIL	接続に失敗しました。
S_OK	関数が成功しました。

解説(Remarks)

この関数を呼び出す前に、機能が存在している必要があります。エラーは get_Errors を使用して取得できます。エラーと情報メッセージは現在のログファイルに記録されます。

データベースに加えた変更は、 CloseDatabase 関数を bCommit に TRUE を設定して呼び出さない限り、ディスクに保存されません。

vtbl 18 HRESULT ExtractCAB(LPWSTR FileName)

ExtractCAB メソッドは、モジュールから埋め込みの .cab ファイルを抽出し、指定したファイルとして保存します。

FileName

LPWSTR

完全修飾された出力先ファイル。BSTR の代わりに LPCWSTR を使用できます。

戻り値

このメソッドは、次のいずれかの値を返します。

値	意味
E_INVALIDARG	引数のいずれかが無効です。
ERROR_OPEN_FAILED as HRESULT	出力ファイルを作成できませんでした。
ERROR_WRITE_FAULT as HRESULT	出力ファイルにデータを書き込めませんでした。
E_FAIL	埋め込みの .cab ファイルにアクセスできません。
S_FALSE	埋め込みの .cab ファイルが見つかりませんでした。
S_OK	関数が成功しました。

vtbl 19 HRESULT ExtractFiles(LPWSTR Path)

ExtractFiles メソッドは、モジュールから埋め込みの .cab ファイルを抽出し、それらのファイルを出力先ディレクトリに書き込みます。詳細については、Merge オブジェクトの ExtractFiles メソッドを参照してください。

Path

LPWSTR

完全修飾された出力先ディレクトリ。BSTR の代わりに LPCWSTR を使用できます。

戻り値

このメソッドは、次のいずれかの値を返します。

値	意味
ERROR_CANNOT_MAKE as HRESULT	出力パスを作成できませんでした。
ERROR_OPEN_FAILED as HRESULT	出力ファイルを作成できませんでした。
ERROR_WRITE_FAULT as HRESULT	出力ファイルにデータを書き込めませんでした。
E_FAIL	埋め込みの .cab ファイルにアクセスできない、または一時ファイルを作成できません。
S_FALSE	埋め込みの .cab ファイルが見つかりませんでした。
S_OK	関数が成功しました。

解説(Remarks)

出力先ディレクトリ内の同じ名前のファイルはすべて上書きされます。パスが存在しない場合は作成されます。

ExtractFiles は、常にパスに短いファイル名を使用してファイルを抽出します。パスに長いファイル名を使用するには、 ExtractFilesEx 関数を使用してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

#define global IID_IMsmMerge "{0ADDA82E-2C26-11D2-AD65-00A0C9AF11A6}"
#usecom global IMsmMerge IID_IMsmMerge "{0ADDA830-2C26-11D2-AD65-00A0C9AF11A6}"
#comfunc global IMsmMerge_OpenDatabase      7 wstr
#comfunc global IMsmMerge_OpenModule        8 wstr,int
#comfunc global IMsmMerge_CloseDatabase     9 int
#comfunc global IMsmMerge_CloseModule       10
#comfunc global IMsmMerge_OpenLog           11 wstr
#comfunc global IMsmMerge_CloseLog          12
#comfunc global IMsmMerge_Log               13 wstr
#comfunc global IMsmMerge_get_Errors        14 sptr
#comfunc global IMsmMerge_get_Dependencies  15 sptr
#comfunc global IMsmMerge_Merge             16 wstr,wstr
#comfunc global IMsmMerge_Connect           17 wstr
#comfunc global IMsmMerge_ExtractCAB        18 wstr
#comfunc global IMsmMerge_ExtractFiles      19 wstr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。