PGET_MODULE_HANDLE_EXW
コールバックシグネチャ
BOOL PGET_MODULE_HANDLE_EXW(
DWORD dwFlags,
LPWSTR lpModuleName,
HMODULE* phModule
);パラメーター
| フィールド | 型 | 説明 |
|---|---|---|
| dwFlags | DWORD | このパラメーターには 0、または次の値の 1 つ以上を指定できます。モジュールの参照カウントがインクリメントされた場合、呼び出し元は、モジュールハンドルが不要になった時点で FreeLibrary 関数を使用して参照カウントをデクリメントする必要があります。 GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS (0x00000004)lpModuleName パラメーターは、モジュール内のアドレスです。 GET_MODULE_HANDLE_EX_FLAG_PIN (0x00000001)FreeLibrary が何回呼び出されても、プロセスが終了するまでモジュールは読み込まれたままになります。 このオプションは、GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT と併用できません。 GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT (0x00000002)モジュールの参照カウントはインクリメントされません。このオプションは GetModuleHandle の動作と同等です。取得したモジュールハンドルを FreeLibrary 関数に渡さないでください。渡すと、DLL が早期にマップ解除される可能性があります。詳細については、「解説」を参照してください。 このオプションは、GET_MODULE_HANDLE_EX_FLAG_PIN と併用できません。 |
| lpModuleName | LPWSTR | 読み込まれているモジュール (.dll ファイルまたは .exe ファイル) の名前、または (dwFlags が GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS の場合は) モジュール内のアドレスです。 モジュール名を指定する場合、ファイル名の拡張子を省略すると、既定のライブラリ拡張子 .dll が付加されます。ファイル名の文字列に末尾のピリオド (.) を含めると、モジュール名に拡張子がないことを示せます。この文字列でパスを指定する必要はありません。パスを指定する場合は、スラッシュ (/) ではなく円記号 () を使用してください。この名前は、呼び出し元プロセスのアドレス空間に現在マップされているモジュールの名前と (大文字と小文字を区別せずに) 比較されます。 このパラメーターが NULL の場合、関数は、呼び出し元プロセスの作成に使用されたファイル (.exe ファイル) のハンドルを返します。 |
| phModule | HMODULE* | 指定されたモジュールのハンドルです。関数が失敗した場合、このパラメーターは GetModuleHandleEx 関数は、LOAD_LIBRARY_AS_DATAFILE フラグを使用して読み込まれたモジュールのハンドルは取得しません。詳細については、LoadLibraryEx を参照してください。 - dwFlags.GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS (0x00000004)lpModuleName パラメーターは、モジュール内のアドレスです。 - dwFlags.GET_MODULE_HANDLE_EX_FLAG_PIN (0x00000001)FreeLibrary が何回呼び出されても、プロセスが終了するまでモジュールは読み込まれたままになります。 このオプションは、GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT と併用できません。 - dwFlags.GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT (0x00000002)モジュールの参照カウントはインクリメントされません。このオプションは GetModuleHandle の動作と同等です。取得したモジュールハンドルを FreeLibrary 関数に渡さないでください。渡すと、DLL が早期にマップ解除される可能性があります。詳細については、「解説」を参照してください。 このオプションは、GET_MODULE_HANDLE_EX_FLAG_PIN と併用できません。 |
公式ドキュメント
指定されたモジュールのモジュールハンドルを取得し、GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT が指定されていない限り、そのモジュールの参照カウントをインクリメントします。モジュールは、呼び出し元プロセスによって読み込まれている必要があります。
戻り値
関数が成功した場合、戻り値は 0 以外の値です。
関数が失敗した場合、戻り値は 0 です。拡張エラー情報を取得するには、GetLastError を参照してください。
解説(Remarks)
返されるハンドルは、グローバルでも継承可能でもありません。複製することも、別のプロセスで使用することもできません。
lpModuleName にパスが含まれておらず、同じベース名と拡張子を持つモジュールが複数読み込まれている場合、どのモジュールハンドルが返されるかは予測できません。この問題を回避するには、パスを指定する、side-by-side アセンブリを使用する、または lpModuleName パラメーターに DLL 名ではなくメモリ位置を指定する、といった方法があります。
dwFlags に GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT が含まれる場合、GetModuleHandleEx 関数は、参照カウントをインクリメントせずにマップ済みモジュールのハンドルを返します。ただし、このハンドルを FreeLibrary 関数に渡すと、マップ済みモジュールの参照カウントはデクリメントされます。したがって、GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT を指定した GetModuleHandleEx が返したハンドルを FreeLibrary 関数に渡さないでください。渡すと、DLL モジュールが早期にマップ解除される可能性があります。
dwFlags に GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT が含まれる場合、マルチスレッドアプリケーションではこの関数を慎重に使用する必要があります。この関数がハンドルを返してから、そのハンドルが使用されるまでの間、モジュールハンドルが有効なままである保証はありません。たとえば、あるスレッドがモジュールハンドルを取得し、それを使用する前に、2 つ目のスレッドがそのモジュールを解放することがあります。その後にシステムが別のモジュールを読み込むと、解放されたばかりのモジュールハンドルが再利用される可能性があります。その結果、最初のスレッドは、意図したものとは異なるモジュールのハンドルを持つことになります。
この関数を使用するアプリケーションをコンパイルするには、_WIN32_WINNT を 0x0501 以降として定義します。詳細については、Windows ヘッダーの使用を参照してください。
libloaderapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版と Unicode 版を自動的に選択するエイリアスとして GetModuleHandleEx を定義しています。エンコーディング中立のエイリアスの使用を、エンコーディング中立ではないコードと混在させると、不一致が生じ、コンパイルエラーや実行時エラーの原因となることがあります。詳細については、関数プロトタイプの規則を参照してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)