Función GetModuleHandleExA (libloaderapi.h)

Artículo
03/11/2023

Recupera un identificador de módulo para el módulo especificado e incrementa el recuento de referencias del módulo a menos que se especifique GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT. El proceso de llamada debe haber cargado el módulo.

Sintaxis

BOOL GetModuleHandleExA(
  [in]           DWORD   dwFlags,
  [in, optional] LPCSTR  lpModuleName,
  [out]          HMODULE *phModule
);

Parámetros

[in] dwFlags

Este parámetro puede ser cero o uno o varios de los valores siguientes. Si se incrementa el recuento de referencias del módulo, el autor de la llamada debe usar la función FreeLibrary para reducir el recuento de referencias cuando el identificador del módulo ya no sea necesario.

GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS (0x00000004)

El parámetro lpModuleName es una dirección del módulo.

GET_MODULE_HANDLE_EX_FLAG_PIN (0x00000001)

El módulo permanece cargado hasta que finaliza el proceso, independientemente de cuántas veces se llame a FreeLibrary .

Esta opción no se puede usar con GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT.

GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT (0x00000002)

El recuento de referencias del módulo no se incrementa. Esta opción es equivalente al comportamiento de GetModuleHandle. No pase el identificador del módulo recuperado a la función FreeLibrary ; si lo hace, puede hacer que el archivo DLL se desasignación prematuramente. Para obtener más información, vea la sección Comentarios.

Esta opción no se puede usar con GET_MODULE_HANDLE_EX_FLAG_PIN.

[in, optional] lpModuleName

Nombre del módulo cargado (ya sea un archivo .dll o .exe) o una dirección del módulo (si dwFlags está GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS).

Para un nombre de módulo, si se omite la extensión de nombre de archivo, se anexa la extensión de biblioteca predeterminada .dll. La cadena de nombre de archivo puede incluir un carácter de punto final (.) para indicar que el nombre del módulo no tiene extensión. La cadena no tiene que especificar una ruta de acceso. Al especificar una ruta de acceso, asegúrese de usar barras diagonales inversas (\), no barras diagonales (/). El nombre se compara (mayúsculas y minúsculas de forma independiente) con los nombres de los módulos asignados actualmente al espacio de direcciones del proceso de llamada.

Si este parámetro es NULL, la función devuelve un identificador al archivo usado para crear el proceso de llamada (.exe archivo).

[out] phModule

Identificador del módulo especificado. Si se produce un error en la función, este parámetro es NULL.

La función GetModuleHandleEx no recupera identificadores de los módulos cargados mediante la marca LOAD_LIBRARY_AS_DATAFILE . Para obtener más información, consulte LoadLibraryEx.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, consulte GetLastError.

Comentarios

El identificador devuelto no es global ni heredable. No se puede duplicar ni usar en otro proceso.

Si lpModuleName no incluye una ruta de acceso y hay más de un módulo cargado con el mismo nombre base y extensión, no puede predecir qué identificador de módulo se devolverá. Para solucionar este problema, puede especificar una ruta de acceso, usar ensamblados en paralelo o especificar una ubicación de memoria en lugar de un nombre DLL en el parámetro lpModuleName .

Si dwFlags contiene GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, la función GetModuleHandleEx devuelve un identificador a un módulo asignado sin incrementar su recuento de referencias. Sin embargo, si este identificador se pasa a la función FreeLibrary , se disminuirá el recuento de referencias del módulo asignado. Por lo tanto, no pase un identificador devuelto por GetModuleHandleEx con GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT a la función FreeLibrary . Si lo hace, puede hacer que un módulo DLL se desasignación prematuramente.

Si dwFlags contiene GET_MODULE_HANDLE_EX_FLAG_UNCHANGED_REFCOUNT, esta función se debe usar cuidadosamente en una aplicación multiproceso. No hay ninguna garantía de que el identificador del módulo permanezca válido entre el momento en que esta función devuelve el identificador y la hora en que se usa. Por ejemplo, un subproceso recupera un identificador de módulo, pero antes de usar el identificador, un segundo subproceso libera el módulo. Si el sistema carga otro módulo, podría reutilizar el identificador del módulo que se liberó recientemente. Por lo tanto, el primer subproceso tendría un identificador para un módulo diferente al previsto.

Para compilar una aplicación que usa esta función, defina _WIN32_WINNT como 0x0501 o posterior. Para obtener más información, vea Usar los encabezados de Windows.

Nota:

El encabezado libloaderapi.h define GetModuleHandleEx como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede provocar errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	libloaderapi.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll