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.

Example

// The following shows how to create a MDI based application
// using a generic CView derived class that is implemented in
// a dynamically loaded MFC Extension DLL.

typedef CRuntimeClass * (*GETDLLVIEW)();

BOOL CMyApp::InitInstance()
{
   // ....
   // Standard AppWizard generated initalization excluded.
   // ...

   // Register the application's document templates.  Document
   // templates serve as the connection between documents,
   // frame windows, and views.

    
   //Load MFC Extension DLL based view class.
   m_hViewDll = AfxLoadLibrary("myview.dll");
   if (!m_hViewDll)
   {
      AfxMessageBox("Error: Cannot find component \"MyView.Dll\"");
      return FALSE;
   }

   GETDLLVIEW GetView = (GETDLLVIEW) GetProcAddress(m_hViewDll,
       "GetView");
   ASSERT (GetView != NULL);

   CMultiDocTemplate* pDocTemplate;
   pDocTemplate = new CMultiDocTemplate(
      IDR_MYTYPE,
      RUNTIME_CLASS(CMyDoc),
      // Custom MDI child frame.
      RUNTIME_CLASS(CChildFrame), 
      //Call our DLL function to return view class.
      GetView());          
   AddDocTemplate(pDocTemplate);

   // ....
   // Standard AppWizard generated initalization excluded.
   // ...
   
   return TRUE;
}


int CMyApp::ExitInstance() 
{
   
   if (m_hViewDll)
   {
      AfxFreeLibrary(m_hViewDll);
      m_hViewDll = NULL;
   }

   return CWinApp::ExitInstance();
}

See Also   AfxFreeLibrary