AfxLoadLibrary

HINSTANCE AFXAPI AfxLoadLibrary( LPCTSTR lpszModuleName );

Return Value

If the function succeeds, the return value is a handle to the module. If the function fails, the return value is NULL.

Parameters

lpszModuleName

Points to a null-terminated string that contains the name of the module (either a .DLL or .EXE file). The name specified is the filename of the module.

If the string specifies a path but the file does not exist in the specified directory, the function fails.

If a path is not specified and the filename extension is omitted, the default extension .DLL is appended. However, the filename string can include a trailing point character (.) to indicate that the module name has no extension. When no path is specified, the function searches for the file in the following sequence:

• The directory from which the application loaded.
  
  
• The current directory.
  
  
• Windows 95: The Windows system directory. Windows NT: The 32-bit Windows system directory. The name of this directory is SYSTEM32.
  
  
• Windows NT only: The 16-bit Windows system directory. There is no Win32 function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM.
  
  
• The Windows directory.
  
  
• The directories that are listed in the PATH environment variable.

Remarks

Use AfxLoadLibrary to map a DLL module. It returns a handle that can be used in GetProcAddress to get the address of a DLL function. AfxLoadLibrary can also be used to map other executable modules.

Each process maintains a reference count for each loaded library module. This reference count is incremented each time AfxLoadLibrary is called and is decremented each time AfxFreeLibrary is called. When the reference count reaches zero, the module is unmapped from the address space of the calling process and the handle is no longer valid.

Be sure to use AfxLoadLibrary and AfxFreeLibrary (instead of the Win32 functions LoadLibrary and FreeLibrary) if your application uses multiple threads. Using AfxLoadLibrary and AfxFreeLibrary insures that the startup and shutdown code that executes when the extension DLL is loaded and unloaded does not corrupt the global MFC state.

See Also   AfxFreeLibrary