winbase.h


LoadLibrary

La función LoadLibrary proyecta el módulo ejecutable especificado en el espacio de direcciones del proceso desde el que se invoca.

Sintaxis

HINSTANCE LoadLibrary(
    LPCTSTR lpLibFileName 	// dirección del nombre de fichero del módulo ejecutable
   );

Parámetros

lpLibFileName: apunta a una cadena terminada con cero con el nombre del módulo ejecutable (puede ser un fichero .DLL o .EXE). El nombre especificado es el nombre de fichero del módulo y no está relacionado con el nombre almacenado en el propio módulo de biblioteca, tal como se especifica por la palabra clave LIBRARY en el fichero de definición de módulo (.DEF).

Si la cadena especifica un camino, pero el fichero no existe en el directorio especificado, la función falla.

Si no se especifica un camino y se omite la extensión de fichero, se añade la extensión .DLL por defecto. Sin embargo, la cadena de nombre puede incluir un punto al final para indicar que el nombre de fichero no tiene extensión. Cuando no se especifica un camino, la función busca el fichero en la siguiente secuencia:

  1. EL directorio desde el que se ha cargado la aplicación.
  2. El directorio actual.
  3. Windows 95: El directorio de sistema de Windows. Se usa la función GetSystemDirectory para obtener el camino de ese directorio.
    Windows NT: El directorio de sistema de 32-bit de Windows. Se usa la función GetSystemDirectory para obtener el camino de ese directorio. El nombre de ese directorio es SYSTEM32.
  4. Windows NT: El directorio de sistema de 16-bit de Windows. No existe una función en el API de Win32 que obtenga el camino de ese directorio, pero será buscado. El nombre de ese directorio es SYSTEM.
  5. El directorio de Windows. Se usa la función GetWindowsDirectory para obtener el camino de ese directorio.
  6. Los directorio listados en la variable de entorno PATH.

El primer directorio en que se busca es el que contiene el proceso que invoca a la función (para más información, ver la función CreateProcess). Hacer esto permite localizar ficheros privados de biblioteca de enlace dinámico (DLL) asociados al proceso sin añadir el camino del directorio del proceso sin que sea necesario añadirlo a la variable de entorno PATH.

Una vez que la función obtiene un camino completo al fichero de módulo de la biblioteca, éste es comparado (sin tener en cuenta mayúsculas ni minúsculas) con los caminos completos de las bibliotecas recientemente cargadas por el proceso. Esas bibliotecas incluyen aquellas cargadas desde que el proceso arrancó hasta la cargada previamente por LoadLibrary pero no descargadas mediante FreeLibrary. Si el camino coincide con el de algún módulo cargado previamente, la función sólo incrementa el contador para el módulo y devuelve el manipulador del módulo para esa biblioteca.

Valor de retorno

Si la función tiene éxito, el valor de retorno es un manipulador del módulo.

Si la función falla, el valor de retorno es NULL. Para obtener información adicional sobre el error, se debe llamar a la función GetLastError.

Observaciones

LoadLibrary se puede usar para proyectar un módulo DLL y retornar un manipulador que se puede usar por GetProcAddress para obtener la dirección de una función de la DLL. LoadLibrary también se puede usar para proeyctar otros módulos ejecutables. Por ejemplo, la función puede especificar un fichero ejecutable .EXE para obtener un manipulador que se puede usar con FindResource o LoadResource.

Los manipuladores de módulo no son globales no se pueden heredar. Una llamada a LoadLibrary por un proceso no produce un manipulador que se pueda usar por otro proceso, por ejemplo, en una llamada a GetProcAddress. El otro proceso debe acer su propia llamada a LoadLibrary para el módulo antes de llamar a GetProcAddress.

Si el módulo es una DLL que todavía no ha sido proyectada por el proceso, el sistema llama a la función DllEntryPoint de la DLL con el valor DLL_PROCESS_ATTACH. Si la función de punto de entrada de la DLL no devuelve TRUE, LoadLibrary falla y devuelve NULL.

Windows 95: si se usa LoadLibrary para cargar un módulo que contiene un recurso cuyo número identificador es mayor de 0x7FFF, LoadLibrary falla.