home *** CD-ROM | disk | FTP | other *** search
/ Tricks of the Windows Gam…ming Gurus (2nd Edition) / Disc2.iso / vc98 / include / edkevent.h < prev    next >
C/C++ Source or Header  |  1998-04-25  |  7KB  |  173 lines
  1. // --edkevent.h-----------------------------------------------------------------
  2. //
  3. // Header file for module containing event logging functions.
  4. //
  5. // Copyright 1986 - 1998 Microsoft Corporation.  All Rights Reserved.
  6. // -----------------------------------------------------------------------------
  7.  
  8. #if !defined(_EDKEVENT_H)
  9. #define _EDKEVENT_H
  10.  
  11. #ifdef __cplusplus
  12. extern "C" {
  13. #endif // __cplusplus
  14.  
  15. //$--EDKEVENTCOUNT--------------------------------------------------------------
  16. //  Structure to hold the counts of the number of each type of event that has 
  17. //  been logged.
  18. // -----------------------------------------------------------------------------
  19. typedef struct _EDKEventCount {
  20.     DWORD    cError;
  21.     DWORD    cWarning;
  22.     DWORD    cInformation;
  23. } EDKEVENTCOUNT, *LPEDKEVENTCOUNT;
  24.  
  25.  
  26. //$--HrEventOpenLog----------------------------------------------------------
  27. //  Initialize event logging for the EDK.
  28. // -----------------------------------------------------------------------------
  29. HRESULT HrEventOpenLog(                // RETURNS: HRESULT
  30.     IN LPSTR pszApplicationName,        // name of this application
  31.     IN LPSTR pszExecutableName,            // name of executable
  32.     IN LPSTR pszEventMessageFile,       // name of event message file
  33.     IN LPSTR pszParameterMessageFile,   // name of parameter message file
  34.     IN LPSTR pszCategoryMessageFile,    // name of category message file
  35.     OUT LPHANDLE phEventSourceOut);        // [returns event logging handle]
  36.  
  37. //$--HrEventUseExisting---------------------------------------------------
  38. //  Initialize event logging for the EDK by connecting to an already open 
  39. //  event log handle.  This allows EventLogMsg() to log events to a handle 
  40. //  that was opened elsewhere.  Calling HrEventCloseLog() after calling 
  41. //  this routine will do internal cleanup but will not close the event log 
  42. //  handle.  One example of where this routine is useful is within a DLL 
  43. //  that is called by EDK code in which event logging has already been 
  44. //  initialized.
  45. // -----------------------------------------------------------------------------
  46. HRESULT HrEventUseExisting(        // RETURNS: HRESULT
  47.     IN HANDLE hExistingEventSource);        // previously opened event log handle
  48.  
  49.  
  50. //$--EventLogMsg----------------------------------------------------------------
  51. //
  52. //  EventLogMsgA -- byte string version
  53. //  EventLogMsgW -- word string version
  54. //
  55. //  Log an event to the event log, and optionally, log the original error(s) 
  56. //  that caused the event.  It has the following parameters:
  57. //
  58. //   DWORD    dwEvent
  59. //   DWORD    cStrings
  60. //  [LPSTR   pszString1]
  61. //  [LPSTR   pszString2]
  62. //  [...................]
  63. //  [LPSTR   pszStringN]
  64. //   DWORD    cErrorCodes
  65. //  [DWORD    dwErrorCode1]
  66. //  [DWORD    dwErrorCode2]
  67. //  [.....................]
  68. //  [DWORD    dwErrorCodeN]
  69. //
  70. //  Each of the above strings and error codes are used as parameters to the 
  71. //  message in the order they appear.  This means that in event messages, 
  72. //  all of the  error message replacement parameters must have higher numbers 
  73. //  than all of the string replacement parameters.  For example:
  74. //
  75. //      EventLogMsg(
  76. //          MYAPP_CANNOT_COPY_FILE, 
  77. //          2, pszSourceFile, pszDestFile, 
  78. //          1, dwError);
  79. //
  80. //  And the message would be defined as:
  81. //
  82. //      MessageId=
  83. //      Severity=Error
  84. //      Facility=Application
  85. //      SymbolicName=MYAPP_CANNOT_COPY_FILE
  86. //      Language=English
  87. //      Cannot copy file from %1 to %2 due to the following error:%n%3.
  88. //      .
  89. //
  90. //  Note: This routine preserves the last error value returned by 
  91. //        GetLastError().
  92. //
  93. // -----------------------------------------------------------------------------
  94.  
  95. //$--EventLogMsgA---------------------------------------------------------------
  96. //  Byte string version of EventLogMsg().
  97. //
  98. //  IMPORTANT!!! The error code count [and error code list] is REQUIRED after 
  99. //  the text string count [and text string list].  Failure to include the 
  100. //  error code argument(s) may cause unexpected results.
  101. // -----------------------------------------------------------------------------
  102. VOID EventLogMsgA(                        // RETURNS: nothing
  103.     IN DWORD dwEvent,                    // error code of event to log
  104.     IN DWORD cStrings,                    // number of text string parameters
  105.     IN ...                                // text string parameters
  106. //    IN DWORD cErrors,                    // number of error code parameters
  107. //    IN ...                                // error code parameters
  108. );
  109.  
  110. //$--EventLogMsgW---------------------------------------------------------------
  111. //  Word string version of EventLogMsg().
  112. //
  113. //  IMPORTANT!!! The error code count [and error code list] is REQUIRED after 
  114. //  the text string count [and text string list].  Failure to include the 
  115. //  error code argument(s) may cause unexpected results.
  116. // -----------------------------------------------------------------------------
  117. VOID EventLogMsgW(                        // RETURNS: nothing
  118.     IN DWORD dwEvent,                    // error code of event to log
  119.     IN DWORD cStrings,                    // number of text string parameters
  120.     IN ...                                // text string parameters
  121. //    IN DWORD cErrors,                    // number of error code parameters
  122. //    IN ...                                // error code parameters
  123. );
  124.  
  125. #ifdef UNICODE
  126. #define EventLogMsg  EventLogMsgW
  127. #else
  128. #define EventLogMsg  EventLogMsgA
  129. #endif // !UNICODE
  130.  
  131.  
  132. //$--HrEventGetCounts--------------------------------------------------------
  133. //  Returns the number of Error, Warning, and Information events logged (by the 
  134. //  current executable).
  135. // -----------------------------------------------------------------------------
  136. HRESULT HrEventGetCounts(            // RETURNS: HRESULT
  137.     OUT LPEDKEVENTCOUNT lpsEventCount);    // structure to return event counts
  138.  
  139.  
  140. //$--HrEventCloseLog---------------------------------------------------------
  141. //  Shut down event logging for the EDK.
  142. // -----------------------------------------------------------------------------
  143. HRESULT HrEventCloseLog();            // RETURNS: HRESULT
  144.  
  145. // $--HrEventGetHandle------------------------------------------------------
  146. //
  147. // DESCRIPTION: Retrieve event handle for this executable.
  148. //
  149. // OUTPUT:  phEventLog   --  event log handle pointer
  150. //
  151. // RETURNS: HRESULT --  NOERROR if successful,
  152. //                      E_INVALIDARG if bad input,
  153. //                      E_FAIL otherwise.
  154. //
  155. // Notes:  
  156. //
  157. // 1) The event handle returned will be NULL if there is
  158. // no open event log.
  159. //
  160. // 2) DLLs may not call this function to retrieve the event handle
  161. // which their parent executable set.  If the parent executable sets
  162. // an event handle, then it must pass the event handle to the DLL.
  163. //
  164. // ----------------------------------------------------------------------------
  165. HRESULT HrEventGetHandle(
  166.         IN HANDLE * phEventLog);       // event log handle pointer
  167.  
  168. #ifdef __cplusplus
  169. }   // end extern "C"
  170. #endif // __cplusplus
  171.  
  172. #endif
  173.