PGET_MODULE_HANDLE_EXA
コールバックシグネチャ
BOOL PGET_MODULE_HANDLE_EXA(
DWORD dwFlags,
LPSTR 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 | LPSTR | 読み込まれているモジュール (.dll ファイルまたは .exe ファイル) の名前、または (dwFlags が GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS の場合は) モジュール内のアドレスです。 モジュール名を指定する場合、ファイル名の拡張子を省略すると、既定のライブラリ拡張子 .dll が付加されます。モジュール名に拡張子が無いことを示すには、ファイル名文字列の末尾にピリオド (.) を含めることができます。この文字列でパスを指定する必要はありません。パスを指定する場合は、スラッシュ (/) ではなく円記号 () を使用してください。名前は、呼び出し元プロセスのアドレス空間に現在マップされているモジュールの名前と (大文字と小文字を区別せずに) 比較されます。 このパラメーターが NULL の場合、関数は呼び出し元プロセスの作成に使用されたファイル (.exe ファイル) のハンドルを返します。 |
| phModule | HMODULE* | 指定されたモジュールのハンドルです。関数が失敗した場合、このパラメーターは NULL になります。 GetModuleHandleEx 関数は、LOAD_LIBRARY_AS_DATAFILE フラグを使用して読み込まれたモジュールのハンドルは取得しません。詳細については LoadLibraryEx を参照してください。 |
公式ドキュメント
指定されたモジュールのモジュールハンドルを取得し、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 が含まれる場合、この関数はマルチスレッドアプリケーションでは慎重に使用する必要があります。この関数がハンドルを返してから、そのハンドルが使用されるまでの間、モジュールハンドルが有効であり続ける保証はありません。たとえば、あるスレッドがモジュールハンドルを取得し、それを使用する前に、別のスレッドがそのモジュールを解放することがあります。システムが別のモジュールを読み込むと、直前に解放されたモジュールハンドルが再利用される可能性があります。そのため、最初のスレッドは意図したものとは異なるモジュールのハンドルを保持することになります。
この関数を使用するアプリケーションをコンパイルするには、_WIN32_WINNT を 0x0501 以降として定義します。詳細については、 Using the Windows Headers を参照してください。
libloaderapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版と Unicode 版を自動的に選択するエイリアスとして GetModuleHandleEx を定義しています。エンコード中立のエイリアスを、エンコード中立でないコードと混在させて使用すると、不一致が生じてコンパイルエラーや実行時エラーの原因となることがあります。詳細については Conventions for Function Prototypes を参照してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)