Back to topJanuary 10, 1997
Building the Code Samples
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. |
All of these code samples should build on your properly installed Win32 Platform SDK. 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 Workstation 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.
Each 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 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 Win32 Platform SDK. Currently this location has a path similar to D:\MSSDK\SAMPLES\OLE\COM, 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, then use MAKEALL.BAT to compile all the samples in the branch.
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 clean up all the code 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.
To build any of the code 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++ 2.x or above, and a properly installed Win32 Platform SDK. It is usually wise to install the Win32 Platform SDK last.
Alternatively, and exclusive of the Platform SDK, you may use an installed 32-bit C++ integrated development environment (IDE). But to do so requires that you treat the generic makefiles provided as external to your IDE. These makefiles require a Microsoft NMAKE-compatible make utility.
The Win32 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 set up your environment by adding something like the following to your AUTOEXEC.BAT file. Under Windows 95, you can manually edit the AUTOEXEC.BAT file to include these commands in it. 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=E:\MSSDK\INCLUDE;D:\MSDEV\INCLUDE;D:\MSDEV\MFC\INCLUDE SET LIB=E:\MSSDK\LIB;D:\MSDEV\LIB;D:\MSDEV\MFC\LIB SET MSSDK=E:\MSSDK SET MSTOOLS=E:\MSSDK SET CPU=i386 SET PATH=C:\WIN95;C:\WIN95\COMMAND;C:\DOS;E:\MSSDK\BIN;D:\MSDEV\BIN
These settings are appropriate for an Intel 80386 or better platform running Windows 95 with both Microsoft Visual C++ and the Win32 Platform SDK installed. On this system, Visual C++ is installed under the D:\MSDEV directory. The Platform SDK is installed under the E:\MSSDK directory. Your disk configuration may be different. The Platform SDK E:\MSSDK directories are all earlier in each path sequence where they must be specified. This sequence assumes that command line compilations are intended to be run in the Command Prompt window.
The D:\MSDEV\MFC\INCLUDE and D:MSDEV\MFC\LIB directories are shown in the INCLUDE and LIB paths, but they are not required to build the tutorial code samples. In this particular setup, Microsoft Foundation Class (MFC) applications are being compiled, as well as straight COM and Win32 applications.
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 Win32 Platform SDK in the \MSSDK\INCLUDE directory. All of the ActiveX 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 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.
Most C++ IDEs can also recognize these makefiles as external and yet still give many of the edit-build-debug benefits of the IDE. For example, in Microsoft's Developer Studio in the Visual C++ 4+ product, you can simply use the File menu's Open Workspace choice to produce a project file by opening the code sample's Win32 makefile as a project.
To open a sample's Win32 makefile as a new project in Visual C++ Developer Studio, follow these steps.
From there you can use the editor, debugger, and project facilities to edit, compile, link, and debug. Some of the 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 may be worthwhile. See your IDE documentation for details on using external makefiles or on creating a native project makefile using existing source files.
Though the code samples are divided into 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.
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 sample:
[destination]
APPUTIL
INC
LIB
REGISTER
MARSHAL
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
Because this tutorial provides a graduated sequence of code samples, certain coding style conventions are used. 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.
Because the ActiveX tutorial code samples are meant to be study devices in addition to being coding skeletons, some consistent conventions for comment header blocks are used. They are:
/*+==========================================================================
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 block of comment text that usually takes more than several lines. Plain block of comment text that usually takes more than several lines. ---------------------------------------------------------------------------*/
/*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*/
/*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*/
/*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*/
/*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*/
/*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*/
/*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.
© 1997 Microsoft Corporation