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