![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to tn012.txt CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [WindowsNT SDKs] / mstools / mfc / doc|
Return to tn012.txt CVS log | Up to [WindowsNT SDKs] / mstools / mfc / doc |
1.1 root 1:
2: Microsoft Foundation Classes Microsoft Corporation
3: Technical Notes
4:
5: #12 : Using MFC with Windows 3.1 Robustness Features
6:
7: Windows 3.1 is a major improvement over Windows 3.0 in the
8: area of robust application development. Windows 3.1 includes
9: a number of new features that enhance the reliability of a
10: Windows application. This technical note describes the
11: use of these features within the MFC library.
12:
13: =============================================================================
14:
15: Windows 3.1 Debug Kernel
16: ========================
17:
18: Testing your MFC application with the debug system executables is probably
19: the best thing you can do to make sure your applications are robust
20: and reliable. The debugging versions of the system executables perform all
21: sorts of useful error checking for you, informing you of any problems
22: that arise with debug output messages.
23:
24: The best way to use the debug system is with two machines: a machine for
25: testing and debugging that has the debug system installed, and a machine for
26: development. If you put a monochrome adapter card in your debug machine,
27: CodeView and debug system output can be directed to the monochrome monitor.
28:
29: But, not everyone can afford to buy a second machine just for debugging. One
30: drawback of installing the debug system on your development machine is that
31: it runs somewhat slower than the standard Windows system, so it slows down
32: your compiler, editor, and other debugging tools.
33:
34: A useful trick for single-machine debugging is to place copies of the system
35: and debug binaries and symbols in a separate directory, and have batch files
36: that copy the appropriate files to your Windows System directory. This way
37: you can exit Windows and switch back and forth quickly between debug and
38: non-debug. The SDK installation program will set this up for then you can
39: switch between debug and nondebug version of Windows with the D2N.BAT and
40: N2D.BAT batch files.
41:
42: If you aren't running with a debugger or a debug terminal, you should run the
43: DBWIN application so you can see the error and warning messages produced by
44: the debug system. This application is included with the SDK.
45:
46: Here are some common programming errors that appear more frequently than they
47: should in shipped Windows applications. Many of these problems can cause
48: random system UAEs and other problems under Windows 3.0. The debug system
49: binaries will help you track down these kinds of problems very quickly:
50:
51: * Passing invalid parameters of all shapes and sizes
52:
53: * Accessing nonexistent window words. In 3.0, a SetWindowWord or
54: SetWindowLong call past the end of the allocated window words (as
55: defined with RegisterClass) would trash internal window manager data
56: structures!
57:
58: * Using handles after they've been deleted or destroyed
59:
60: * Using a DC after it has been released
61:
62: * Deleting GDI objects before they're deselected from a DC
63:
64: * Forgetting to delete GDI bitmaps, brushes, pens, or other GDI
65: or USER objects when an application terminates
66:
67: * Writing past the end of an allocated memory block
68:
69: * Reading or writing through a memory pointer after it has been freed
70:
71: * Forgetting to export window procedures and other callbacks
72:
73: * Forgetting to use MakeProcInstance with dialog procs and other
74: callbacks (alternatively, you can use the MS C/C++ 7.0 feature
75: of marking these functions as EXPORT in their declaration.)
76:
77: * Shipping an app without running it with the debugging KERNEL, USER,
78: and GDI.
79:
80:
81: MFC Diagnostics
82: ===============
83:
84: In addition, the Microsoft Foundation Classes ship with a
85: set of robustness features that are compiled and linked only in the
86: debug build of the library (those library variants ending with a 'd'.)
87: Use of these features in the applications you write and in the
88: classes you design will greatly improve both the runtime and
89: compile time error trapping of your application. These functions
90: are outlined below, but all are documented in the Class Library
91: Reference manual.
92:
93: Every class in MFC includes a class invariant, AssertValid. This
94: member function is called to verify the "sanity" of a C++ object.
95: You call use this function whenever objects (or pointers or
96: references to objects) are passed as parameters. The macro
97: ASSERT_VALID(pObject) is supplied so that these calls are not
98: compiled for retail builds. Your class' implementation of this
99: function should first call the base class AssertValid explicitly
100: before doing any derived class specific validation.
101:
102: Parameter validation is another important feature. Aside from
103: validating objects, it is also important to validate buffers
104: and string constants. The global function AfxIsValidAddress should
105: be used to verify the validity of a buffer/length pair. The
106: Class Library Reference provides you with specific information
107: on this API.
108:
109: Every class in MFC implements a Dump member function, which
110: permits you to view the state of an object in an ASCII format. This
111: function can be called from CodeView or placed within #ifdef _DEBUG
112: /#endif portions of your code. You should supply a Dump member
113: for classes that you implement. As with AssertValid, you should
114: first explicitly call your base class Dump member function. The
115: output of Dump is routed to the "afxDump" CDumpContext which
116: by default goes to the CodeView output window or to your debug
117: terminal. You can also use the DBWIN program to view the output of
118: afxDump. The source file \C700\MFC\SRC\DUMPINIT.CPP includes information
119: on how to route afxDump to another destination.
120:
121: TRACE is a macro that behaves much like printf, only routes
122: output to the afxDump location. You should use TRACE statements
123: to indicate tricky or exceptional places in your code. As with
124: other robustness features, TRACE is only meaningful in the
125: debug library, and has no affect in the retail build. The MFC library
126: includes a number of built in TRACE statements for tracking the
127: flow of messages. Please see TN007.TXT for more information of
128: the debug trace information.
129:
130: ASSERT is a runtime check for the validity of a statement. You
131: should use ASSERTs liberally throughout your program. Any place
132: you have a comment to the affect:
133: /* lpStr should be NULL at this point */
134: you should replace that with a runtime assert:
135: ASSERT(lpStr == NULL);
136: The compiler cannot understand English, but it can execute
137: code! ASSERT statements have no affect in retails builds. If
138: you need the side effects of an ASSERT to occur in the retail build
139: as well, then use the VERIFY macro.
140:
141: MFC also includes an extensive diagnostic memory allocator. You
142: diagnostic memory allocator to make sure that you free all memory
143: resources before your program exits. The diagnostic
144: allocator will track the source file and line number of an
145: allocation, so if you use the CMemoryState::DumpAllObjectsSince
146: API you can locate any remaining allocations. A good place to
147: use this API is in the ExitInstance member function of CWinApp
148: (which you can override, but be sure to call the base class
149: ExitInstance.) Additionally, if you have a rather tricky piece
150: of code that does lots of allocations and deallocations, you can
151: use the CMemoryState::Checkpoint and CMemoryState::Difference
152: APIs to be sure to leave the world in a steady state after
153: executing such code.
154:
155:
156: Windows 3.1 STRICT type checking
157: ================================
158:
159: STRICT type checking is an option available with the new
160: WINDOWS.H header file. Before a discussion of the use
161: of STRICT, a brief description of C++ typesafe linkage is
162: in order.
163:
164: In C++ you are permitted to have many functions with the
165: same name, so long as these functions have different formal
166: parameter lists. In order to have unique link symbols, the
167: C++ compiler will "decorate" these names using an algorithm
168: that encodes information about a function such as the name,
169: number and type of formal parameters, calling convention, etc.
170: This newly generated name is used as the external link symbol
171: for the function. This is known as typesafe linkage and is a
172: big benefit of C++. This name decoration does not apply to
173: functions within an extern "C" block, and is why all APIs in
174: WINDOWS.H are in such a block.
175:
176: STRICT typechecking in WINDOWS.H attempts to imitate C++ type
177: safety for C by using distinct types to represent all the different
178: HANDLES in Windows. So for example, STRICT prevents you from
179: mistakenly passing an HPEN to a routine expecting an HBITMAP.
180: Since the Windows APIs are all within extern "C" { } blocks,
181: they are not decorated in the manner described above. STRICT
182: plays tricks with the C compiler by changing the types of
183: the various Windows typedefs to make them unique (specifically
184: it uses different pointer types to represent HANDLEs, which cannot
185: be freely converted without an explicit cast.)
186:
187: As you can see, if you have STRICT typechecking enabled in
188: one file, but not in another, the C++ compiler will generate
189: different external link symbols for a single function. This
190: will result in link time errors. Therefore, it is recommended
191: that you use STRICT typechecking only for C modules (those that
192: end in .C). Additionally, STRICT is a compile time only
193: option, so once you sucessfully compile your code the benefits
194: of STRICT are completely realized.
195:
196: MFC accomplishes all of STRICT static typechecking, plus a whole
197: lot more, by using the C++ language. Therefore, STRICT is disabled
198: by default. If you wish to use STRICT you will need to recompile
199: the MFC libraries that you regularly use (because of typesafe
200: linkage, the external link symbols are different between STRICT
201: and non-STRICT.)
202:
203: The following are guidelines for using STRICT with C/C++/MFC.
204:
205: If you have existing Windows 3.0 C code and you wish to keep it as C code,
206: you can either work to make it STRICT compliant or not, that option is
207: yours. Be sure to use C++ conventions for your exported header file
208: such as putting extern "C" { } around your C APIs if you intend on
209: using the header file within any C++ code. If you have existing Windows
210: 3.1 STRICT C code, then moving it to C++/MFC eliminates the need for
211: STRICT.
212:
213: For any C code that you have, the use of STRICT is optional
214: and encouraged. For C++ code, you should use STRICT with
215: great care, if at all, because of the issues of typesafe linkage.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.