COM Tutorial Samples

Tutorial Home

Previous Lesson

Lesson List

Next Lesson

DLLUSER - EXE User of a DLL

SUMMARY

The DLLUSER sample introduces the basic skeleton for an EXE that implicitly loads a Win32 DLL and makes calls to it. In this case, DLLUSER works with the DLLSKEL.DLL dynamic link library from the DLLSKEL lesson. You must build DLLSKEL before you try to build DLLUSER.EXE, because the DLLSKEL makefile copies the necessary DLLSKEL.H, DLLSKEL.LIB, and DLLSKEL.DLL files it produces into the DLLUSER sibling directory.

For functional descriptions and a tutorial code tour of DLLUSER, see the Code Tour section in DLLUSER.HTM. For details on the external user operation of DLLUSER, see both the Usage and Operation sections in DLLUSER.HTM. To read DLLUSER.HTM, run TUTORIAL.EXE in the main tutorial directory and click the DLLUSER lesson in the table of lessons. You can also achieve the same thing by clicking the DLLUSER.HTM file after locating the main tutorial directory in the Windows Explorer. See also the DLLSKEL.HTM file in the main tutorial directory for more details on how DLLSKEL works and exposes its services to DLLUSER.

For details on setting up your system to build and test the code samples in this COM Tutorial series, see Building the Code Samples. The supplied makefile (MAKEFILE) is Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE command in the Command Prompt window.

For convenient use in Microsoft's Visual Studio, a project file is provided for each sample. To load the project for the DLLUSER sample, you can run Visual Studio at the Command Prompt in the sample's directory as follows:

 
    MSDEV DLLUSER.DSP
 

You can also simply double-click the DLLUSER.DSP file in the Windows Explorer to load a sample's project into Visual Studio. From within Visual Studio you can then browse the C++ classes of the sample source and generally perform the other edit-compile-debug operations. Note that, as part of the Platform SDK, the compilation of these samples from within Visual Studio requires the proper setting of directory paths in Visual Studio. For more details, see Building the Code Samples.

Usage

This DLLUSER.EXE application is provided to interact with DLLSKEL.DLL. DLLUSER recognizes no command line arguments. See the Operation section below for more details.

Run the Sample

The client sample and other related samples must be compiled before you can run the client. For more details on building the samples, see Building the Code Samples.

If you have already built the appropriate samples, DLLUSER.EXE is the client executable to run for this sample.

OPERATION

The DLLUSER.EXE application provides the main user interface for this lesson. It exercises the associated, but independent, DLLSKEL.DLL. Here is a summary of operation from the standpoint of DLLUSER.EXE as a controller of DLLSKEL.DLL:

Menu Selection: File/Exit
Quits DLLUSER.

Menu Selection: Test/Call DLLSKEL.DLL
Calls the DllHelloBox function of DLLSKEL.DLL, which displays a message box with the following format: DLLSKEL instance [i] hello. Shared count = [c], where [i] is the DLLUSER process instance count and [c] is the shared count of the number of times the DllHelloBox function has been called from any DLLUSER.

Menu Selection: Test/About DLLSKEL.DLL
Calls the DllAboutBox function of DLLSKEL.DLL, which displays the About dialog box for the DLL itself, as opposed to the About dialog box for the controlling DLLUSER application.

Menu Selection: Help/DLLUSER Tutorial
Opens the DLLUSER.HTM tutorial file in the Web browser.

Menu Selection: Help/DLLSKEL Tutorial
Opens the DLLSKEL.HTM tutorial file in the Web browser.

Menu Selection: Help/Read Source File
Opens one of this sample's source files. After you select a file name, the Windows Notepad utility displays the selected source file. This command illustrates how to program the use of the File Open common dialog box.

Menu Selection: Help/About DLLUSER
Displays the About dialog box for this application, a standard part of this series of code samples. The command illustrates how to program the use of the CAboutBox class provided by APPUTIL.LIB.

CODE TOUR

 
Files          Description
DLLUSER.TXT    Short sample description.
MAKEFILE       The generic makefile for building the code sample
               application of this tutorial lesson.
DLLUSER.H      The include file for the DLLUSER.EXE application. Contains
               class declarations, function prototypes, and resource
               identifiers.
DLLUSER.CPP    The main implementation file for DLLUSER.EXE. Has WinMain
               and CMainWindow implementation.
DLLUSER.RC     The DLLUSER.EXE application resource definition file.
DLLUSER.ICO    The icon resource for DLLUSER.EXE.
DLLSKEL.H      The include file for declaring as imported the service
               functions in DLLSKEL.DLL. This file is copied to the
               sibling ..\INC directory during the build of DLLSKEL.
DLLSKEL.LIB    The library file for use in linking to the function
               calls used in DLLSKEL.DLL. This file is copied to the
               sibling ..\LIB directory during the build of DLLSKEL.
DLLSKEL.DLL    The binary DLLSKEL dynamic link libary. This file is copied
               to this DLLUSER directory during the build of DLLSKEL.
DLLSKEL.DSP    Microsoft Visual Studio Project file.
 

This DLLUSER code sample offers another basic skeleton that is used in subsequent code samples in this tutorial. You can also use it as a source skeleton in your own programming. DLLUSER is based largely on the previous EXESKEL code sample. You can study the code comments in DLLUSER to learn more about this C++ skeleton.

In the context of an COM Tutorial series of code samples, the goal of DLLUSER is to show the use of services in the separate DLLSKEL DLL. The DLLUSER application also illustrates how to link a Win32 C++ EXE application to a separate Win32 DLL and call the exported services.

DLLUSER.CPP defines the WinMain entry function for the entire application, which contains the message loop. Like EXESKEL, DLLUSER.CPP makes use of many of the utility classes and services provided by APPUTIL. For more details on APPUTIL, study the source code located in the sibling APPUTIL directory and APPUTIL.HTM in the main tutorial directory.

DLLUSER.H exploits APPUTIL's CVirWindow abstract base class (see APPUTIL.H) to derive and implement a CMainWindow class. CMainWindow encapsulates the main window functionality into a convenient C++ object. It handles initialization of new instances of the main window and the message dispatching of the main window procedure. This main window procedure is a method of CMainWindow.

For the DLLUSER application to make use of the exported functions in DLLSKEL, the DLLSKEL.H file must be included. The default behavior of DLLSKEL.H is to serve calling applications that import the functions residing in the DLL.

For example, the following prototype appers in DLLSKEL.H.

 
  STDENTRY_(BOOL) DllAboutBox(HWND hWnd);
  

When the DllAboutBox function is imported, this prototype declaration is expanded as follows.

 
  extern "C" __declspec(dllimport) BOOL WINAPI DllAboutBox(HWND hWnd);
  

The WINAPI macro expands to various things, depending on the build environment, but generally stipulates the calling convention (for example, __stdcall). See WIN32.MAK and the standard Windows include file WINDEF.H for more details on the WINAPI macro.

The two sample calls in DLLUSER are shown in the following fragment from the menu handling in DLLUSER.CPP.

 
    ...
    case IDM_TEST_DLLHELLO:
      // Call the DLLSKEL DLL to say hello from it.
      ::DllHelloBox(m_hWnd);
      break;

    case IDM_TEST_DLLABOUT:
      // Call the DLLSKEL DLL to show the DLL's About Box.
      ::DllAboutBox(m_hWnd);
      break;
    ...
  

Both calls pass the window handle of the main DLLUSER window as a parent window of the dialog boxes that DLLSKEL.DLL will put on the screen.

Back to page top