DLLUSER - DLL User Application Skeleton


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 below. See also the DLLSKEL.TXT file (in the sibling
DLLSKEL directory) for more details on how DLLSKEL works and exposes its
services to DLLUSER. For details on the external user operation of
DLLUSER, see the Operation section below.

In general, to set up your system to build and test the code samples in
this OLE Tutorial series, see TUTORIAL.TXT for details. The supplied
makefile is Microsoft NMAKE-compatible. To create a debug build, issue the
NMAKE command at the command prompt.

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.


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 <h> says hello for a count of <c>,
where <h> is the instance handle in hexadecimal of the called DLL and <c>
is the count in decimal of the number of times the DllHelloBox function
has been called.

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/Read DLLUSER.TXT
Starts the Windows Notepad utility and displays DLLUSER.TXT (this file).

Menu Selection: Help/Read DLLSKEL.TXT
Starts the Windows Notepad utility and displays DLLSKEL.TXT from the
sibling DLLSKEL directory.

Menu Selection: Help/Read Source File
Opens one of this lesson'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.

Menu Selection: Help/About DLLSKEL
Displays the About dialog box for the partner DLL that is used by this
application. In this series of code samples, partner DLLs like DLLSKEL
are given their own About dialog boxes in the native resources of the DLL.
This menu selection issues the DLL call to display this About dialog box.


CODE TOUR
=========

Files          Description

DLLUSER.TXT    This file.
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.

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 OLE 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 APPUTIL
directory, a sibling to EXESKEL, and APPUTIL.TXT.

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.
