COM Logo COM Tutorial Samples Tutorial Home
Tutorial Home
Lesson List
Lesson List
First Lesson
First Lesson

Using the Code Samples

Building the Code Samples
Extracting the Code Samples
Coding Style Conventions


Building the Code Samples

To build any of the COM Tutorial Samples, your computer environment must be set up to build Win32 C++ applications with a properly installed 32-bit C++ compiler, linker, and resource compiler that are compatible with Microsoft Visual C++® 4.x or above, and a properly installed Platform SDK. It is usually wise to install the Platform SDK last. The Platform SDK provides .H include and .LIB library files needed for the COM functionality coded in the samples.

Because this sample series originated as an integral part of the Platform SDK, the tutorial narrative assumes an environment with the Platform SDK properly installed. However, releases of Microsoft Visual C++ after version 4.0 may also provide the .H include and .LIB library files needed for compilation. In such cases, installation of the Platform SDK may not be required to compile the samples.

To successfully run the REMCLIEN, FRESERVE, and FRECLIEN samples requires system facilities that are only available in more recent versions of the 32-bit Windows operating systems. REMCLIEN, FRESERVE, and FRECLIEN require the Windows NT version 4.0 or later. The REMCLIEN, FRESERVE, and FRECLIEN samples will build but will not run on the Windows 95 operating system until Distributed COM (DCOM) and free threaded COM are supported in that operating system. This support is available for the Windows 95 operating system in the DCOM95 add on. DCOM95 can currently be obtained by download from Microsoft's world wide Web site at: http://www.microsoft.com/com/.

Each sample directory has the necessary source files to build and run the sample. The parent sample directory has a MAKEALL.BAT file, which you can run from the command prompt to make all the code samples in the branch below. See the MAKEALL.BAT file for details on usage. If your environment is set up to build Win32 C++ applications, you can simply run MAKEALL.BAT from the directory where it resides to build all the code samples in the branch below. MAKEALL ensures the correct order to the build so that all the code sample dependencies are satisfied.

The main directory also has a makefile that builds all the tutorial code samples using options similar to those supported by MAKEALL.BAT. See this makefile for details on options. This makefile assumes that the entire code samples branch is installed as part of the Platform SDK. Currently this location has a path similar to D:\MSSDK\SAMPLES\COM\TUTSAMP, where D: represents the installation drive. If you have extracted the tutorial code sample branch (eg, directory COM and below) to another location outside the Platform SDK (or if you obtained the sample set as a separate download from the Microsoft World Wide Web site), then use MAKEALL.BAT to compile all the samples in the branch. In general, MAKEALL.BAT is the recommended way to go. A LOGMALL.BAT file is also provided. It does the same as MAKEALL.BAT except that it logs all compilation output to file ERRORLOG.TXT in the main tutorial directory.

Two batch files, REGALL.BAT and UNREGALL.BAT, are also provided in the main directory to register and unregister all COM servers in the tutorial code sample series. To register all servers, run REGALL.BAT file from the main directory. To unregister all servers, run UNREGALL.BAT in the same manner. These batch files require a prior build of the REGISTER, MARSHAL, DLLSERVE, LICSERVE, LOCSERVE, APTSERVE, FRESERVE, and CONSERVE code samples. If you perform a normal build of the code samples, the server makefiles will automatically register the servers. In this case you do not need to run the REGALL.BAT batch file.

Run the CLEANALL.BAT batch file to perform an exhaustive CLEANALL of all the COM Tutorial Samples. WARNING: This batch file deletes all Visual Studio®: project files and other temporary work files created by VC++® in the samples. All of the COM servers that are built in the tutorial code samples are unregistered from the registry. All executable EXE and DLL files are deleted. All debug symbol files are deleted. Files that are generated in a variety of build environments are also deleted.

Run 'MAKEALL CLEAN' to perform a faster but more modest cleanup of all the code samples. This cleaning operation does not attempt to be as comprehensive as that performed by CLEANALL.BAT. The .OBJ files are deleted but the output binaries are retained. The COM servers are not unregistered from the registry.

The installed Platform SDK provides a SETENV.BAT file located in the \MSSDK directory that you can run to set up your environment for building applications that use the Platform SDK.

You can also manually set up your environment by adding something like the following to your AUTOEXEC.BAT file. Under Windows 95, you can edit the AUTOEXEC.BAT file to include these commands. Under Windows NT, you can edit or add these settings to your environment variables using the System dialog that you can run from the Control Panel.

 
  SET INCLUDE=D:\MSSDK\INCLUDE;C:\MSDEV\INCLUDE;C:\MSDEV\ATL\INCLUDE
  SET LIB=D:\MSSDK\LIB;C:\MSDEV\LIB
  SET MSSDK=D:\MSSDK
  SET MSTOOLS=D:\MSSDK
  SET CPU=i386
  SET PATH=C:\WIN95;C:\WIN95\COMMAND;C:\DOS;D:\MSSDK\BIN;C:\MSDEV\BIN
 

These settings are appropriate for an Intel 80386 or better platform running Windows 95 with both Microsoft Visual C++ and the Platform SDK installed. On this system, Visual C++ version 5.0 is installed under the C:\MSDEV directory. The Platform SDK is installed under the D:\MSSDK directory. Your disk configuration may be different. The Platform SDK directories (i.e., those with D:\MSSDK in them above) are all earlier in each path sequence. This sequence assumes that command line compilations are intended to be run in the Command Prompt window and that the .H include and .LIB library files in the Platform SDK are preferred for those compilations.

The CPU environment variable is defined to control the Win32 builds, depending on the platform. Current possible values are i386, MIPS, ALPHA, and PPC. For more details, see the WIN32.MAK file provided in the Platform SDK in the \MSSDK\INCLUDE directory. All of the COM tutorial code sample makefiles include WIN32.MAK.

The makefiles for each of the code samples in this series are generic Win32 makefiles and are meant to be built from the Command Prompt window. They assume Microsoft compiler and linker tools and will probably need some modification to work with other tools. Most compiler/linker command line switches are specified by macros that are defined in the WIN32.MAK makefile include file (supplied as part of the Platform SDK). The MAKEALL.BAT file and each respective code sample makefile support the following common options for invocation from the Command Prompt window to control the nature of the build:

 
  NMAKE invocation   MAKEALL invocation    Effect
  -----------------  --------------------  ---------------------------------
  nmake              makeall               Compile with debug info.
  nmake nodebug=1    makeall "nodebug=1"   Compile without debug info.
  nmake profile=1    makeall "profile=1"   Compile with profiling info.
  nmake tune=1       makeall "tune=1"      With working set tuner info.
  nmake unicode=1    makeall "unicode=1"   Compile for UNICODE.
  nmake clean        makeall clean         Delete temporary binaries.
  nmake cleanall     makeall cleanall      Delete all generated files.
 

For the MAKEALL.BAT invocations you need the quotes as shown. The nodebug, profile, and tune options are mutually exclusive: you may use only one of them (or none) for a given compilation/link. To compile the samples to run with UNICODE strings, use the unicode=1 option. The default is to compile for the traditional ANSI string support, because you can then easily run on either Windows NT or Windows 95. Currently, you must compile without UNICODE to run these code samples on Windows 95. You can freely compile and run with or without UNICODE on Windows NT. Be careful that APPUTIL is always compiled with the same options as the other code samples you may be separately compiling. This is especially true for the unicode=1 option.

You may use an installed 32-bit C++ integrated development environment (IDE) to build the samples using the generic makefiles provided. But to do so requires that within your IDE you treat the generic makefiles as 'external' makefiles. The makefiles provided require a Microsoft NMAKE-compatible make utility.

Most C++ IDEs can recognize these makefiles as external and yet still give many of the edit-build-debug benefits of the IDE. For example, in Microsoft's Visual Studio® 97 product, you can simply use the File menu's Open Workspace choice to produce a workspace by opening an appropriately named copy (e.g., EXESKEL.MAK) of the code sample's Win32 makefile.

For convenient use in Microsoft's Visual Studio, a project file is provided for each sample. This file has the DSP extension. An ALLSAMPS.DSW workspace file is also provided in the main directory so that you can compile all the samples at once from within Visual Studio.

To load the appropriate project for a sample, you can run Visual Studio at the Command Prompt in the sample's directory as follows:

 
    MSDEV <MYSAMPLE>.DSP
 

You can also simply double-click the .DSP file in the Windows Explorer to load a sample's workspace 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. To set the directory paths, perform the following steps (assuming Visual Studio 97).

  1. Run Microsoft Visual Studio (Visual C++).
  2. Choose "Options..." on the "Tools" menu.
  3. Choose the "Directories" tab in the "Options" dialog.
  4. In the "Show Directories For" drop-down list, select "Executable files" and enter the BIN directory path for your installed Platform SDK (for example, D:\MSSDK\BIN). Click the up arrow button to move this newly entered path so that it is the first entry in the "Directories" list.
  5. In the "Show Directories For" drop-down list select "Include files" and enter the INCLUDE directory path for your installed Platform SDK (for example, D:\MSSDK\INCLUDE). Click the up arrow button to move this newly entered path so that it is the first entry in the "Directories" list.
  6. In the "Show Directories For" drop-down list select "Library files" and enter the LIB directory path for your installed Platform SDK (for example, D:\MSSDK\LIB). Click the up arrow buttons to move this newly entered path so that it is the first entry in the "Directories" list.
  7. Click the OK button in the "Options" dialog to complete the settings.

From there you can use the editor, debugger, and project facilities to edit, compile, link, and debug. Note that in versions of Microsoft Visual C++ earlier than 5.0, the steps in Visual Studio may be a little different.

Other visual IDEs can also easily generate one of their native project makefiles, given the existing source files of a code sample. If you are using such an IDE, generating such a native project makefile can be very worthwhile because it offers a way to browse the C++ classes of the program. See your IDE documentation for details on using external makefiles or on creating a native project makefile using a set of existing source files.

Aside from the dependence on the common code in the sibling APPUTIL, INC, and LIB directories, many code samples are self-contained. You need to build APPUTIL before you build any of the other code samples. Some samples later in the sequence may work with the compiled results of earlier samples. These code sample interdependencies are as follows.

Any: Build of any code sample needs prior build of APPUTIL.
DLLUSER: Build or run needs prior build of DLLSKEL.
COMUSER: Build or run needs prior build of COMOBJ.
DLLSERVE: Build needs prior build of REGISTER.
DLLCLIEN: Run needs prior build of DLLSERVE.
LICSERVE: Build needs prior build of REGISTER.
LICCLIEN: Run needs prior build of LICSERVE and DLLSERVE.
MARSHAL: Build needs prior build of REGISTER.
LOCSERVE: Build or run needs prior build of REGISTER and MARSHAL.
LOCCLIEN: Run needs prior build of LOCSERVE.
APTSERVE: Build or run needs prior build of REGISTER and MARSHAL.
APTCLIEN: Run needs prior build of APTSERVE.
REMCLIEN: Build or run needs prior build of REGISTER and MARSHAL on local (client) machine. Run needs prior build of REGISTER, MARSHAL, and APTSERVE on remote (server) machine.
FRESERVE: Build needs prior build of REGISTER.
FRECLIEN: Run needs prior build of FRESERVE.
CONSERVE: Build needs prior build of REGISTER.
CONCLIEN: Run needs prior build of CONSERVE.
STOSERVE: Build needs prior build of REGISTER.
STOCLIEN: Run needs prior build of STOSERVE.
PERSERVE: Build needs prior build of REGISTER.
PERTEXT: Build needs prior build of REGISTER.
PERDRAW: Build needs prior build of REGISTER.
PERCLIEN: Run needs prior build of PERSERVE, PERTEXT, and PERDRAW.
DCDMARSH: Build needs prior build of REGISTER.
DCDSERVE: Build or run needs prior build of REGISTER and DCDMARSH.
DCOMDRAW: Build or run needs prior build of REGISTER and DCDMARSH on local (client) machine. Run needs prior build of REGISTER, DCDMARSH, and DCOMDRAW on remote (server) machine.

Top Back to page top


Extracting the Code Samples

Though the code samples are divided into a series of tutorial lessons, the appropriate sample groupings can easily be extracted from the collection. Most of the individual sample directories are meant to work in conjunction with at least one other sample directory. The component-related samples consist of a client and server pair, with the server requiring the use of the REGISTER sample utility. Here is a summary of the sample groupings and how to extract each group as a buildable unit. For each sample grouping, copy the content of the directories shown. The parent [destination] directory shown requires no content from the samples branch. However, the help menus in the running samples do assume that the appropriate tutorial .HTM help files are located in this parent [destination] directory.

For the Win32 READTUT application:

 
  [destination]
    APPUTIL
    INC
    LIB
    READTUT
 

For the Win32 EXE skeleton application:

 
  [destination]
    APPUTIL
    INC
    LIB
    EXESKEL
 

For the Win32 DLL skeleton:

 
  [destination]
    APPUTIL
    INC
    LIB
    DLLSKEL
    DLLUSER
 

For the basic COM object samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    COMOBJ
    COMUSER
 

For the basic in-process DLL component client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    DLLSERVE
    DLLCLIEN
 

For the licensed component client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    LICSERVE
    LICCLIEN
 

For the standard marshaling samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    MARSHAL
    MARSHAL2
 

For the out-of-process local client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    MARSHAL
    LOCSERVE
    LOCCLIEN
 

For the apartment model client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    MARSHAL
    APTSERVE
    APTCLIEN
 

For the DCOM (Distributed COM) client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    MARSHAL
    APTSERVE
    REMCLIEN
 

For the free threading client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    FRESERVE
    FRECLIEN
 

For the connectable COM object client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    CONSERVE
    CONCLIEN
 

For the structured storage client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    STOSERVE
    STOCLIEN
 

For the persistent object client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    PERSERVE
    PERTEXT
    PERDRAW
    PERCLIEN
 

For the DCOM security client/server samples:

 
  [destination]
    APPUTIL
    INC
    LIB
    REGISTER
    DCDMARSH
    DCDSERVE
    DCOMDRAW
 

Top Back to page top


Coding Style Conventions

Coding style conventions are used in this sample series to aid clarity and consistency. The "Hungarian" notation conventions are used. These have become a common coding practice in Win32 programming. They include variable prefix notations that give to variable names a suggestion of the type of the variable. The following prefixes are common:

 
  a       Array
  b       BOOL (int)
  by      Unsigned Char (byte)
  c       Char
  cb      Count of bytes
  cr      Color reference value
  cx      Count of x (short)
  dw      DWORD (unsigned long)
  f       Flags (usually multiple bit values)
  fn      Function
  g_      global
  h       Handle
  i       Integer
  l       Long
  lp      Long pointer
  m_      Data member of a class
  n       Short int
  p       Pointer
  s       String
  sz      Zero terminated String
  tm      Text metric
  u       Unsigned int
  ul      Unsigned long (ULONG)
  w       WORD (unsigned short)
  x,y     x, y coordinates (short)
 

These are often combined, as in:

 
  pszMyString    A pointer to a string.
  m_pszMyString  A pointer to a string that is a data member of a class.
 

Other conventions are:

 
  CMyClass          Prefix 'C' for C++ class names.
  COMyObjectClass   Prefix 'CO' for COM object class names.
  CFMyClassFactory  Prefix 'CF' for COM class factory names.
  IMyInterface      Prefix 'I' for COM interface class names.
  CImpIMyInterface  Prefix 'CImpI' for COM interface implementation classes.
 

Some consistent conventions for comment header blocks are used in this sample series. They are:

File Header

 
/*+==========================================================================
  File:      MYFILE.EXT

  Summary:   Brief summary of the file contents and purpose.

  Classes:   Classes declared or used (in source files).

  Functions: Functions exported (in source files).

  Origin:    Indications of where content may have come from. This is not
             a change history but rather a reference to the
             editor-inheritance behind the content or other indications
             about the origin of the source.

----------------------------------------------------------------------------
  Copyright and Legal notices.
  Copyright and Legal notices.
==========================================================================+*/
 

Plain Comment Block

 
/*---------------------------------------------------------------------------
  Plain block of comment text that usually takes more than several lines.
  Plain block of comment text that usually takes more than several lines.
---------------------------------------------------------------------------*/
 

Class Declaration Header

 
/*C+C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C+++C
  Class:    CMyClass

  Summary:  Short summary of purpose and content of CMyClass.
            Short summary of purpose and content of CMyClass.

  Methods:  MyMethodOne
              Short description of MyMethodOne.
            MyMethodTwo
              Short description of MyMethodTwo.
            CMyClass
              Constructor.
            ~CMyClass
              Destructor.
C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C---C-C*/
 

Class Method Definition Header

 
/*M+M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M+++M
  Method:   CMyClass::MyMethodOne

  Summary:  Short summary of purpose and content of MyMethodOne.
            Short summary of purpose and content of MyMethodOne.

  Args:     MYTYPE MyArgOne
              Short description of argument MyArgOne.
            MYTYPE MyArgTwo
              Short description of argument MyArgTwo.

  Modifies: [list of member data variables modified by this method].

  Returns:  MYRETURNTYPE
              Short description of meaning of the return type values.
M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M---M-M*/
 

Unexported or Local Function

 
/*F+F++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  Function: MyLocalFunction

  Summary:  What MyLocalFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
------------------------------------------------------------------------F-F*/
 

Exported Function Definition Header

 
/*F+F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F+++F
  Function: MyFunction

  Summary:  What MyFunction is for and what it does.

  Args:     MYTYPE MyFunctionArgument1
              Description.
            MYTYPE MyFunctionArgument1
              Description.

  Returns:  MyReturnType
              Description.
F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F---F-F*/
 

COM Interface Declaration Header

 
/*I+I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I+++I
  Interface: IMyInterface

  Summary:   Short summary of what features the interface can bring to
             a COM Component.

  Methods:   MYTYPE MyMethodOne
               Description.
             MYTYPE MyMethodTwo
               Description.
I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I---I-I*/
 

COM Object Class Declaration Header

 
/*O+O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O+++O
  ObjectClass: COMyCOMObject

  Summary:     Short summary of purpose and content of this object.

  Interfaces:  IUnknown
                 Standard interface providing COM object features.
               IMyInterfaceOne
                 Description.
               IMyInterfaceTwo
                 Description.

  Aggregation: [whether this COM Object is aggregatable or not]
O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O---O-O*/
  

All of these comment block conventions have consistent beginning and ending token strings. This consistency supports automatic processing of the headers in some fashion. For example, AWK scripts can be written to filter out only the function headers into a separate text file that can serve the basis for a specification document. Similarly, tools like the unsupported AUTODUCK utility (currently available on the Microsoft Developer Network Development Library CD-ROM) can be used to process the comment blocks in these headers. The following beginning and ending tokens are used:

 
  /*+     File Header Begin
  +*/     File Header End

  /*-     Plain comment block Header Begin
  -*/     Plain comment block Header End

  /*C     Class Header Begin
  C*/     Class Header End

  /*M     Method Header Begin
  M*/     Method Header End

  /*F     Function Header Begin
  F*/     Function Header End

  /*I     Interface Header Begin
  I*/     Interface Header End

  /*O     COM Object Class Header Begin
  O*/     COM Object Class Header End
 

These headers can also be used as visual cues for rapid scanning of source files. They also provide convenience for rapidly getting to some source location if you set up search strings in your editor and then 'repeat last search' to quickly locate these headers. For example, the search string "M+M" will locate the start of method headers, and "M-M" will locate the beginning of the actual method definition/implementation code.

Top Back to page top

© 1995-1998 Microsoft Corporation