Función GetModuleHandleA (libloaderapi.h)

Artículo
08/24/2023

Recupera un identificador de módulo para el módulo especificado. El proceso de llamada debe haber cargado el módulo.

Para evitar las condiciones de carrera descritas en la sección Comentarios, use la función GetModuleHandleEx .

Sintaxis

HMODULE GetModuleHandleA(
  [in, optional] LPCSTR lpModuleName
);

Parámetros

[in, optional] lpModuleName

Nombre del módulo cargado (ya sea un archivo .dll o .exe). Si se omite la extensión de nombre de archivo, se anexará 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, GetModuleHandle devuelve un identificador al archivo usado para crear el proceso de llamada (.exe archivo).

La función GetModuleHandle no recupera identificadores para los módulos cargados mediante la marca LOAD_LIBRARY_AS_DATAFILE . Para obtener más información, vea LoadLibraryEx.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador para el módulo especificado.

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

Comentarios

El identificador devuelto no es global ni se puede heredar. 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 usar GetModuleHandleEx para especificar una ubicación de memoria en lugar de un nombre DLL.

La función GetModuleHandle 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 GetModuleHandle a la función FreeLibrary . Si lo hace, un módulo DLL se desasignación prematuramente.

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, supongamos que 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.

Ejemplos

Para obtener un ejemplo, consulte Uso de pinceles.

Nota:

El encabezado libloaderapi.h define GetModuleHandle 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 neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en 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 (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll