Move logutil docs into header and standardize inline wrapper methods.

1 files changed, 181 insertions, 21 deletions

diff --git a/src/libs/dutil/WixToolset.DUtil/inc/logutil.h b/src/libs/dutil/WixToolset.DUtil/inc/logutil.h
index 8f38e0ce..0ad8510a 100644
--- a/src/libs/dutil/WixToolset.DUtil/inc/logutil.h
+++ b/src/libs/dutil/WixToolset.DUtil/inc/logutil.h
@@ -24,14 +24,29 @@ typedef HRESULT (DAPI *PFN_LOGSTRINGWORKRAW)(
 // structs
 
 // functions
+/********************************************************************
+ IsLogInitialized - Checks if log is currently initialized.
+********************************************************************/
 BOOL DAPI IsLogInitialized();
 
+/********************************************************************
+ IsLogOpen - Checks if log is currently initialized and open.
+********************************************************************/
 BOOL DAPI IsLogOpen();
 
+/********************************************************************
+ LogInitialize - initializes the logutil API
+
+********************************************************************/
 void DAPI LogInitialize(
     __in_opt HMODULE hModule
     );
 
+/********************************************************************
+ LogOpen - creates an application log file
+
+ NOTE: if wzExt is null then wzLog is path to desired log else wzLog and wzExt are used to generate log name
+********************************************************************/
 HRESULT DAPI LogOpen(
     __in_z_opt LPCWSTR wzDirectory,
     __in_z LPCWSTR wzLog,
@@ -42,13 +57,26 @@ HRESULT DAPI LogOpen(
     __out_z_opt LPWSTR* psczLogPath
     );
 
+/********************************************************************
+ LogDisable - closes any open files and disables in memory logging.
+
+********************************************************************/
 void DAPI LogDisable();
 
+/********************************************************************
+ LogRedirect - Redirects all logging strings to the specified
+               function - or set NULL to disable the hook
+********************************************************************/
 void DAPI LogRedirect(
     __in_opt PFN_LOGSTRINGWORKRAW vpfLogStringWorkRaw,
     __in_opt LPVOID pvContext
     );
 
+/********************************************************************
+ LogRename - Renames a logfile, moving its contents to a new path,
+             and re-opening the file for appending at the new
+             location
+********************************************************************/
 HRESULT DAPI LogRename(
     __in_z LPCWSTR wzNewPath
     );
@@ -61,52 +89,119 @@ void DAPI LogUninitialize(
     __in BOOL fFooter
     );
 
+/********************************************************************
+ LogIsOpen - returns whether log file is open or note
+
+********************************************************************/
 BOOL DAPI LogIsOpen();
 
+/********************************************************************
+ LogSetSpecialParams - sets a special beginline string, endline
+                       string, post-timestamp string, etc.
+********************************************************************/
 HRESULT DAPI LogSetSpecialParams(
     __in_z_opt LPCWSTR wzSpecialBeginLine,
     __in_z_opt LPCWSTR wzSpecialAfterTimeStamp,
     __in_z_opt LPCWSTR wzSpecialEndLine
     );
 
+/********************************************************************
+ LogSetLevel - sets the logging level
+
+ NOTE: returns previous logging level
+********************************************************************/
 REPORT_LEVEL DAPI LogSetLevel(
     __in REPORT_LEVEL rl,
     __in BOOL fLogChange
     );
 
+/********************************************************************
+ LogGetLevel - gets the current logging level
+
+********************************************************************/
 REPORT_LEVEL DAPI LogGetLevel();
 
+/********************************************************************
+ LogGetPath - gets the current log path
+
+********************************************************************/
 HRESULT DAPI LogGetPath(
     __out_ecount_z(cchLogPath) LPWSTR pwzLogPath, 
     __in DWORD cchLogPath
     );
 
+/********************************************************************
+ LogGetHandle - gets the current log file handle
+
+********************************************************************/
 HANDLE DAPI LogGetHandle();
 
-HRESULT DAPIV LogString(
-    __in REPORT_LEVEL rl,
-    __in_z __format_string LPCSTR szFormat,
-    ...
-    );
+/********************************************************************
+ LogStringArgs - implementation of LogString
 
+********************************************************************/
 HRESULT DAPI LogStringArgs(
     __in REPORT_LEVEL rl,
     __in_z __format_string LPCSTR szFormat,
     __in va_list args
     );
 
-HRESULT DAPIV LogStringLine(
+/********************************************************************
+ LogString - write a string to the log
+
+ NOTE: use printf formatting ("%ls", "%d", etc.)
+********************************************************************/
+inline HRESULT LogString(
     __in REPORT_LEVEL rl,
     __in_z __format_string LPCSTR szFormat,
     ...
-    );
+    )
+{
+    HRESULT hr = S_OK;
+    va_list args;
+
+    va_start(args, szFormat);
+    hr = LogStringArgs(rl, szFormat, args);
+    va_end(args);
 
+    return hr;
+}
+
+/********************************************************************
+ LogStringLineArgs - implementation of LogStringLine
+
+********************************************************************/
 HRESULT DAPI LogStringLineArgs(
     __in REPORT_LEVEL rl,
     __in_z __format_string LPCSTR szFormat,
     __in va_list args
     );
 
+/********************************************************************
+ LogStringLine - write a string plus LOGUTIL_NEWLINE to the log
+
+ NOTE: use printf formatting ("%ls", "%d", etc.)
+********************************************************************/
+inline HRESULT LogStringLine(
+    __in REPORT_LEVEL rl,
+    __in_z __format_string LPCSTR szFormat,
+    ...
+    )
+{
+    HRESULT hr = S_OK;
+    va_list args;
+
+    va_start(args, szFormat);
+    hr = LogStringLineArgs(rl, szFormat, args);
+    va_end(args);
+
+    return hr;
+}
+
+/********************************************************************
+ LogIdModuleArgs - implementation of LogIdModule
+
+********************************************************************/
 HRESULT DAPI LogIdModuleArgs(
     __in REPORT_LEVEL rl,
     __in DWORD dwLogId,
@@ -114,31 +209,32 @@ HRESULT DAPI LogIdModuleArgs(
     __in va_list args
     );
 
-/* 
- * Wraps LogIdModuleArgs, so inline to save the function call
- */
+/********************************************************************
+ LogIdModule - write a string embedded in a MESSAGETABLE in the specified module to the log
 
-inline HRESULT LogId(
+ NOTE: uses format string from MESSAGETABLE resource
+********************************************************************/
+inline HRESULT LogIdModule(
     __in REPORT_LEVEL rl,
     __in DWORD dwLogId,
+    __in_opt HMODULE hModule,
     ...
     )
 {
     HRESULT hr = S_OK;
     va_list args;
 
-    va_start(args, dwLogId);
-    hr = LogIdModuleArgs(rl, dwLogId, NULL, args);
+    va_start(args, hModule);
+    hr = LogIdModuleArgs(rl, dwLogId, hModule, args);
     va_end(args);
 
     return hr;
 }
 
+/********************************************************************
+ LogIdArgs - inline wrapper for LogIdModuleArgs, passing NULL for hModule
 
-/* 
- * Wraps LogIdModuleArgs, so inline to save the function call
- */
- 
+********************************************************************/
 inline HRESULT LogIdArgs(
     __in REPORT_LEVEL rl,
     __in DWORD dwLogId,
@@ -148,18 +244,64 @@ inline HRESULT LogIdArgs(
     return LogIdModuleArgs(rl, dwLogId, NULL, args);
 }
 
-HRESULT DAPIV LogErrorString(
-    __in HRESULT hrError,
-    __in_z __format_string LPCSTR szFormat,
+/********************************************************************
+ LogId - write a string embedded in a MESSAGETABLE in the default module to the log
+
+ NOTE: uses format string from MESSAGETABLE resource
+********************************************************************/
+inline HRESULT LogId(
+    __in REPORT_LEVEL rl,
+    __in DWORD dwLogId,
     ...
-    );
+    )
+{
+    HRESULT hr = S_OK;
+    va_list args;
+
+    va_start(args, dwLogId);
+    hr = LogIdArgs(rl, dwLogId, args);
+    va_end(args);
+
+    return hr;
+}
 
+/********************************************************************
+ LogErrorStringArgs - implementation of LogErrorString
+
+********************************************************************/
 HRESULT DAPI LogErrorStringArgs(
     __in HRESULT hrError,
     __in_z __format_string LPCSTR szFormat,
     __in va_list args
     );
 
+/********************************************************************
+ LogErrorString - write an error to the log
+
+ NOTE: use printf formatting ("%ls", "%d", etc.)
+********************************************************************/
+inline HRESULT LogErrorString(
+    __in HRESULT hrError,
+    __in_z __format_string LPCSTR szFormat,
+    ...
+    )
+{
+    HRESULT hr  = S_OK;
+
+    va_list args;
+    va_start(args, szFormat);
+    hr = LogErrorStringArgs(hrError, szFormat, args);
+    va_end(args);
+
+    return hr;
+}
+
+/********************************************************************
+ LogErrorIdModule - write an error string embedded in the specified module in a MESSAGETABLE to the log
+
+ NOTE:  uses format string from MESSAGETABLE resource
+        can log no more than three strings in the error message
+********************************************************************/
 HRESULT DAPI LogErrorIdModule(
     __in HRESULT hrError,
     __in DWORD dwLogId,
@@ -169,6 +311,12 @@ HRESULT DAPI LogErrorIdModule(
     __in_z_opt LPCWSTR wzString3
     );
 
+/********************************************************************
+ LogErrorId - write an error string embedded in the default module in a MESSAGETABLE to the log
+
+ NOTE:  uses format string from MESSAGETABLE resource
+        can log no more than three strings in the error message
+********************************************************************/
 inline HRESULT LogErrorId(
     __in HRESULT hrError,
     __in DWORD dwLogId,
@@ -180,10 +328,22 @@ inline HRESULT LogErrorId(
     return LogErrorIdModule(hrError, dwLogId, NULL, wzString1, wzString2, wzString3);
 }
 
+/********************************************************************
+ LogHeader - write a standard header to the log
+
+********************************************************************/
 HRESULT DAPI LogHeader();
 
+/********************************************************************
+ LogFooter - write a standard footer to the log
+
+********************************************************************/
 HRESULT DAPI LogFooter();
 
+/********************************************************************
+ LogStringWorkRaw - Write a raw, unformatted string to the log
+
+********************************************************************/
 HRESULT LogStringWorkRaw(
     __in_z LPCSTR szLogData
     );