 | ||
|
| ||
| ||
|
| ||
Using the Code Samples |
 |
 Tutorial Home |
Lesson List |
 First Lesson |
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 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 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\MFC\INCLUDE SET LIB=D:\MSSDK\LIB;C:\MSDEV\LIB;C:\MSDEV\MFC\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 4.2 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 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 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 Developer Studio® in the Visual C++ 5+ product, you can simply use the File menu's Open Workspace choice to produce a project file by opening an appropriately named copy of the code sample's Win32 makefile.
To open a sample's Win32 makefile and create a matching new project in Visual C++ Developer Studio® version 5+, follow these steps.
From there you can use the editor, debugger, and project facilities to edit, compile, link, and debug. Note that in versions of VC++ earlier than 5.0 the above steps may be a little different. For example, with version 4.x you can open the MAKEFILE file directly (via Open Project Workspace) and a subsequent Save As dialog permits you to name the project file <sample>.MAK.
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 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. |
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:
Back to top
[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
Because this tutorial covers a graduated sequence of code samples, certain coding style conventions are used 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.
Because the COM Tutorial 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.
Did you find this material useful? Gripes? Compliments? Suggestions for other articles? Write us!
© 1999 Microsoft Corporation. All rights reserved. Terms of use.