home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / msdn_vcb / samples / vc98 / com / freethrd / server / apputil.txt < prev    next >
Encoding:
Text File  |  1998-04-03  |  12.4 KB  |  258 lines
  1. APPUTIL - Application Utility Library
  2.  
  3.  
  4. SUMMARY
  5. =======
  6.  
  7. The APPUTIL library provides utility classes and functions that are
  8. useful for making simple C++ Win32 Windows applications. APPUTIL is
  9. provided as part of the Win32 OLE Tutorial code samples.
  10.  
  11. For functional descriptions and a tutorial code tour of APPUTIL, see
  12. the Code Tour section below.
  13.  
  14. For details on setting up your system to build and test the code samples
  15. in this OLE Tutorial series, see TUTORIAL.TXT. The supplied MAKEFILE is
  16. Microsoft NMAKE-compatible. To create a debug build, issue the NMAKE
  17. command in the Command Prompt window.
  18.  
  19. Usage
  20. -----
  21.  
  22. APPUTIL.LIB is meant to be statically linked to modules (.EXEs or .DLLs)
  23. that use it. You include APPUTIL.H in the module that uses features of
  24. APPUTIL.LIB. You must also include APPUTIL.LIB in the LINK command of
  25. your application's makefile. For an example of the use of APPUTIL.LIB,
  26. see the EXESKEL code sample.
  27.  
  28. Classes
  29. -------
  30.  
  31. The classes provided are: CVirWindow, CVirDialog, CAboutBox, CMsgBox,
  32. CMsgLog, CSendLog, and CThreaded.
  33.  
  34. Functions
  35. ---------
  36.  
  37. The functions provided are: WindowProc, DialogProc, UcToAnsi,
  38. CreateColorScalePalette, PaintWindow, FileExist, MakeFamilyPath, CmdExec,
  39. ReadMe, ReadMeFile, ReadSource, and OutputDebugFmt.
  40.  
  41. There are also a series of A_ ANSII versions of OLE service helper
  42. functions. The A_ functions are used in conjunction with a matching
  43. series of macros in APPUTIL.H to permit compilation of the code samples
  44. under both ANSII (default) and UNICODE. These macros and matching
  45. A_ functions are for OLE service calls that only accept Unicode string
  46. parameters. For example, the standard OLE StgIsStorageFile function
  47. only accepts a Unicode string. When compiling a sample for ANSII
  48. (ie, UNICODE is not defined), a macro substitutes any StgIsStorageFile
  49. calls into A_StgIsStorageFile calls. A_StgIsStorageFile is implemented
  50. here in APPUTIL. A_StgIsStorageFile takes the input ANSII string
  51. that is passed and converts it into a Unicode string prior to making a
  52. call to the actual OLE StgIsStorageFile function.
  53.  
  54.  
  55. CODE TOUR
  56. =========
  57.  
  58. File          Description
  59.  
  60. APPUTIL.TXT   This file.
  61. MAKEFILE      The generic Win32 makefile for this APPUTIL library.
  62. APPUTIL.H     The include file for the APPUTIL library. Contains the
  63.               class declarations and function prototypes.
  64. APPUTIL.CPP   The main implementation file for APPUTIL.
  65.  
  66. An abstract base class, CVirWindow, is declared in APPUTIL.H as an aid in
  67. treating a window as a C++ object. Using the CVirWindow class, a window
  68. procedure can directly access class members by dereferencing a pointer to
  69. an object instance of this class. Through GWL_USERDATA in GetWindowLong
  70. and SetWindowLong, the WindowProc member function has access to the "this"
  71. pointer. The global WindowProc function is still used, but this scheme
  72. allows the global function to forward most message handling to the
  73. WindowProc member function of a specific object instance of CVirWindow.
  74. The global WindowProc receives the "this" pointer as the lpCreateParams
  75. member passed as part of the WM_NCCREATE message. It save the "this"
  76. pointer in the GWL_USERDATA field of the window structure.
  77.  
  78. An abstract base class, CVirDialog, which is similar to CVirWindow, is
  79. also declared as an aid in treating a dialog box as a C++ object. Using
  80. the CVirDialog class, a dialog box procedure can directly access class
  81. members by dereferencing a pointer to an object instance of this class.
  82. Through GWL_USERDATA in GetWindowLong and SetWindowLong, the DialogProc
  83. member function has access to the "this" pointer. The global DialogProc
  84. function is still used, but this scheme allows the global function to
  85. defer most message handling to the DialogProc member function of a
  86. specific object instance of CVirDialog.  The functionality is very
  87. similar to CVirWindow described above.
  88.  
  89. The CAboutBox class is declared to allow creation of a common About dialog
  90. box in applications. The class is derived from the CVirDialog abstract
  91. class and illustrates its use.
  92.  
  93. The CMsgBox class is declared to provide simple message boxes to display
  94. error and notice messages. The message strings in the message box can be
  95. specified as string literals, string variables, or resource string
  96. identifiers. The Error and Note methods take string literals or string
  97. variables. The ErrorID and NoteID methods take resource string identifiers.
  98. In addition, the Notice message box methods have variants that support
  99. message string formatting in the style of the C standard library function
  100. printf. These member functions support a variable argument list, NoteFmt,
  101. and NoteFmtID.
  102.  
  103. The CMsgLog class is declared to provide a facility for logging debug trace
  104. messages to a Listbox control. This class is for code samples that use
  105. debug messages to announce internal activity in the code being studied.
  106. This message log listbox can be directed to occupy the entire client area
  107. of the parent window. An argument to the Create method determines whether
  108. the log occupies a detached child window or the entire client area as an
  109. integral child window. Message output member functions can use either
  110. string resource identifier arguments to retrieve the message strings from
  111. the application's resources, or string variables to retrieve the message
  112. strings directly. The CMsgLog::MsgFmt method is provided to allow message
  113. formatting in the style of the C standard library function wsprintf. This
  114. member function supports a variable argument list. The CMsgLog::Copy method
  115. is provided to copy the entire contents of the message log to the Windows
  116. Clipboard.
  117.  
  118. The CMsgLog logging facility is for examining the tutorial code samples.
  119. It works in parallel with the standard OutputDebugString capability. If
  120. you are compiling with NODEBUG=1, the debug output is not compiled. In this
  121. case, logging support is still available, because it is an integral part
  122. of the code sample itself. When compiling for debugging, both outputs are
  123. provided for flexibility. Most C++ debuggers have an output window that
  124. will display the debug output strings, but the logging facility works
  125. whether or not you are running the application under a debugger.
  126.  
  127. The CSendLog trace logging facility is also provided. It operates much like
  128. the CMsgLog facility, except that it is intended for an application that
  129. logs its activity in an application running in another process. This
  130. facility is useful in an out-of-process local server that logs its
  131. internal behavior to a display in a client .EXE. CSendLog uses the Win32
  132. SendMessage function with the WM_COPYDATA message to send a block of text
  133. data from one process to another. CSendLog duplicates some of the
  134. capability of CMsgLog by allowing a local server to have its own log
  135. display. The destination of the logging can therefore be switched between
  136. the client's logging display and the local server's logging display by
  137. calling the LogToServer method.
  138.  
  139. The CThreaded class is provided as a utility base class for providing
  140. functionality in derived classes that offer mutually exclusive access
  141. among multiple threads to data in objects of the derived class. Derive
  142. your class from CThreaded to inherit these features. A typical example of
  143. a method in the derived class that exploits these features follows.
  144.  
  145.   void CServer::Unlock(void)
  146.   {
  147.     if (OwnThis())
  148.     {
  149.       m_cLocks -= 1;
  150.       if (m_cLocks < 0)
  151.         m_cLocks = 0;
  152.  
  153.       if (0L == m_cObjects && 0L == m_cLocks && IsWindow(m_hWndServer))
  154.         PostMessage(m_hWndServer, WM_CLOSE, 0, 0L);
  155.  
  156.       UnOwnThis();
  157.     }
  158.  
  159.     return;
  160.   }
  161.  
  162. This Unlock method implements numerous thread-safe accesses and changes to
  163. the guarded m_cLocks member variable. CServer was derived public from
  164. CThreaded. Two CThreaded methods are of value here: OwnThis and UnOwnThis
  165. are virtual functions in CThreaded that have default defintions that
  166. enforce mutually exclusive access to data in objects of the derived class
  167. (like CServer here). You use bracketed pairs of these OwnThis and
  168. UnOwnThis methods, as above, to code the protection. OwnThis blocks the
  169. currently executing thread until any currently "owning" threads execute
  170. the UnOwnThis method. OwnThis returns true if ownership is granted. See
  171. the CThreaded method definitions in APPUTIL.CPP for more details.
  172.  
  173. Some general utility functions and macros provided by APPUTIL are
  174. briefly described below.
  175.  
  176. OLE often deals with parameters that are pointers to pointers (void**).
  177. To capture this as a type, a PPVOID typedef is provided.
  178.  
  179. The DELETE_POINTER macro deletes the object pointed to by a pointer and sets
  180. the pointer to NULL.
  181.  
  182. The RELEASE_INTERFACE macro releases a pointer to an interface and sets the
  183. pointer to NULL.
  184.  
  185. lRandom is a simple DWORD pseudo-random number generator.
  186.  
  187. Two utility functions are provided for creating color scale palettes and
  188. for painting windows with such colors: CreateColorScalePalette and
  189. PaintWindow. Lifted from the GDIDEMO sample in the Win32 samples of the
  190. Win32 SDK. They are used in these tutorial samples to add color background
  191. to the standard Aboutbox dialog.
  192.  
  193. The FileExist utility function indicates whether a specified file exists.
  194.  
  195. The MakeFamilyPath utility function uses GetModuleFileName to dynamically
  196. determine the path to the module currently executing and construct a
  197. "family" variant of that path with the proper file name extension for a
  198. particular purpose. Various such extensions (for example, .HLP, .TXT, and
  199. .LIC) are defined in APPUTIL.H for use with this MakeFamilyPath function.
  200.  
  201. The ReadMe utility function is provided to start a reader on the
  202. <sample>.TXT file that accompanies the current executable. The Windows
  203. Notepad (NOTEPAD.EXE) is the default reader. You can specify a different
  204. reader by modifying EDITOR_FILE_STR in APPUTIL.H.
  205.  
  206. Like ReadMe, the ReadMeFile utility function is provided to start a reader
  207. on a specified <sample>.TXT file.
  208.  
  209. The ReadSource utility function is provided to display the Open common
  210. dialog box so the user can select any of the source files for the current
  211. code sample and start a reader on that file. The Windows Notepad
  212. (NOTEPAD.EXE) is the default reader. You can specify a different reader by
  213. modifying EDITOR_FILE_STR in APPUTIL.H
  214.  
  215. Then OutputDebugFmt utility function is provided to support formatted
  216. (printf-style) variable argument output to the debugger. This function
  217. wraps the standard OutputDebugString function.
  218.  
  219. A set of debug output macros is provided to obtain source file and line
  220. number information for the debug output. These macros use the function
  221. OutputDebugFmt to support variable argument lists in the format
  222. of the debug output display string. The debug output macros are:
  223.  
  224. Macro Description
  225.  
  226. ODS   Output debug string literal.
  227.       Example:  ODS("String Literal").
  228. ODFn  Output formatted debug string using printf-style format string
  229.       and a variable argument list to correspond to the format.
  230.       Examples: ODF1("Integer=%i", iInteger);
  231.                 ODF2("Integer=%i String=%s \r\n", iInteger, szString);
  232.  
  233. A set of debug trace logging macros is provided to obtain source file and
  234. line number information for the debug output while also logging these
  235. messages to a built-in CMsgLog message logging facility in the
  236. application. These macros also output the same messages to the debugger
  237. using the standard OutputDebugString call. These are convenience macros to
  238. perform both the message logging that the application requires and to
  239. output the same messages to the debugger, if the application was compiled
  240. for debugging and you are running it under a debugger aware of such
  241. output. Like the ODFn macros, these macros form a series. For the string
  242. literal arguments, do not use the TEXT macro--it is provided inside
  243. the macro.
  244.  
  245. Macro     Description
  246.  
  247. LOG       Log a string literal message.
  248.           Example: LOG("String Literal");
  249. LOGFn     Log a formatted message using printf-style format string
  250.           and a variable argument list to correspond to the format.
  251.           Examples: LOGF1("Integer=%i", iInteger);
  252.                     LOGF2("Integer=%i String=%s \r\n", iInteger, szString);
  253. LOGID     Log a message string retrieved from the module's resources.
  254.           Example:  LOGID(ID_OF_MY_STRING_IN_THE_RESOURCES);
  255. LOGERROR  Check an error code and if it is an error then fetch the matching
  256.           error string message from the system tables and log the error.
  257.           Example: LOGERROR("SysApiThatWasCalled:", ErrorCodeReturned);
  258.