Move logutil docs into header and standardize inline wrapper methods.

2 files changed, 181 insertions, 186 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
     );
diff --git a/src/libs/dutil/WixToolset.DUtil/logutil.cpp b/src/libs/dutil/WixToolset.DUtil/logutil.cpp
index 1453d1d2..606279c7 100644
--- a/src/libs/dutil/WixToolset.DUtil/logutil.cpp
+++ b/src/libs/dutil/WixToolset.DUtil/logutil.cpp
@@ -65,27 +65,17 @@ static PFN_LOGSTRINGWORKRAW s_vpfLogStringWorkRaw = NULL;
 static LPVOID s_vpvLogStringWorkRawContext = NULL;
 
 
-/********************************************************************
- IsLogInitialized - Checks if log is currently initialized.
-********************************************************************/
 extern "C" BOOL DAPI IsLogInitialized()
 {
     return LogUtil_fInitializedCriticalSection;
 }
 
-/********************************************************************
- IsLogOpen - Checks if log is currently initialized and open.
-********************************************************************/
 extern "C" BOOL DAPI IsLogOpen()
 {
     return (INVALID_HANDLE_VALUE != LogUtil_hLog && NULL != LogUtil_sczLogPath);
 }
 
 
-/********************************************************************
- LogInitialize - initializes the logutil API
-
-********************************************************************/
 extern "C" void DAPI LogInitialize(
     __in_opt HMODULE hModule
     )
@@ -100,11 +90,6 @@ extern "C" void DAPI LogInitialize(
 }
 
 
-/********************************************************************
- 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
-********************************************************************/
 extern "C" HRESULT DAPI LogOpen(
     __in_z_opt LPCWSTR wzDirectory,
     __in_z LPCWSTR wzLog,
@@ -195,10 +180,6 @@ LExit:
 }
 
 
-/********************************************************************
- LogDisable - closes any open files and disables in memory logging.
-
-********************************************************************/
 void DAPI LogDisable()
 {
     ::EnterCriticalSection(&LogUtil_csLog);
@@ -213,10 +194,6 @@ 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
@@ -231,11 +208,6 @@ void DAPI LogRedirect(
 }
 
 
-/********************************************************************
- 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
     )
@@ -309,20 +281,12 @@ extern "C" void DAPI LogUninitialize(
 }
 
 
-/********************************************************************
- LogIsOpen - returns whether log file is open or note
-
-********************************************************************/
 extern "C" BOOL DAPI LogIsOpen()
 {
     return INVALID_HANDLE_VALUE != LogUtil_hLog;
 }
 
 
-/********************************************************************
- 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,
@@ -368,11 +332,6 @@ LExit:
     return hr;
 }
 
-/********************************************************************
- LogSetLevel - sets the logging level
-
- NOTE: returns previous logging level
-********************************************************************/
 extern "C" REPORT_LEVEL DAPI LogSetLevel(
     __in REPORT_LEVEL rl,
     __in BOOL fLogChange
@@ -416,20 +375,12 @@ extern "C" REPORT_LEVEL DAPI LogSetLevel(
 }
 
 
-/********************************************************************
- LogGetLevel - gets the current logging level
-
-********************************************************************/
 extern "C" REPORT_LEVEL DAPI LogGetLevel()
 {
     return LogUtil_rlCurrent;
 }
 
 
-/********************************************************************
- LogGetPath - gets the current log path
-
-********************************************************************/
 extern "C" HRESULT DAPI LogGetPath(
     __out_ecount_z(cchLogPath) LPWSTR pwzLogPath,
     __in DWORD cchLogPath
@@ -451,37 +402,12 @@ LExit:
 }
 
 
-/********************************************************************
- LogGetHandle - gets the current log file handle
-
-********************************************************************/
 extern "C" HANDLE DAPI LogGetHandle()
 {
     return LogUtil_hLog;
 }
 
 
-/********************************************************************
- LogString - write a string to the log
-
- NOTE: use printf formatting ("%ls", "%d", etc.)
-********************************************************************/
-extern "C" HRESULT DAPIV 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;
-}
-
 extern "C" HRESULT DAPI LogStringArgs(
     __in REPORT_LEVEL rl,
     __in_z __format_string LPCSTR szFormat,
@@ -502,27 +428,6 @@ LExit:
     return hr;
 }
 
-/********************************************************************
- LogStringLine - write a string plus LOGUTIL_NEWLINE to the log
-
- NOTE: use printf formatting ("%ls", "%d", etc.)
-********************************************************************/
-extern "C" HRESULT DAPIV 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;
-}
-
 extern "C" HRESULT DAPI LogStringLineArgs(
     __in REPORT_LEVEL rl,
     __in_z __format_string LPCSTR szFormat,
@@ -543,11 +448,6 @@ LExit:
     return hr;
 }
 
-/********************************************************************
- LogIdModuleArgs - write a string embedded in a MESSAGETABLE to the log
-
- NOTE: uses format string from MESSAGETABLE resource
-********************************************************************/
 
 extern "C" HRESULT DAPI LogIdModuleArgs(
     __in REPORT_LEVEL rl,
@@ -570,53 +470,6 @@ LExit:
     return hr;
 }
 
-extern "C" HRESULT DAPI LogIdModule(
-    __in REPORT_LEVEL rl,
-    __in DWORD dwLogId,
-    __in_opt HMODULE hModule,
-    ...
-    )
-{
-    AssertSz(REPORT_NONE != rl, "REPORT_NONE is not a valid logging level");
-    HRESULT hr = S_OK;
-    va_list args;
-
-    if (REPORT_ERROR != rl && LogUtil_rlCurrent < rl)
-    {
-        ExitFunction1(hr = S_FALSE);
-    }
-
-    va_start(args, hModule);
-    hr = LogIdWork(rl, (hModule) ? hModule : LogUtil_hModule, dwLogId, args, TRUE);
-    va_end(args);
-
-LExit:
-    return hr;
-}
-
-
-
-
-/********************************************************************
- LogError - write an error to the log
-
- NOTE: use printf formatting ("%ls", "%d", etc.)
-********************************************************************/
-extern "C" HRESULT DAPIV 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;
-}
 
 extern "C" HRESULT DAPI LogErrorStringArgs(
     __in HRESULT hrError,
@@ -648,12 +501,6 @@ LExit:
 }
 
 
-/********************************************************************
- LogErrorIdModule - write an error string embedded in a MESSAGETABLE to the log
-
- NOTE:  uses format string from MESSAGETABLE resource
-        can log no more than three strings in the error message
-********************************************************************/
 extern "C" HRESULT DAPI LogErrorIdModule(
     __in HRESULT hrError,
     __in DWORD dwLogId,
@@ -681,10 +528,6 @@ LExit:
     return hr;
 }
 
-/********************************************************************
- LogHeader - write a standard header to the log
-
-********************************************************************/
 extern "C" HRESULT DAPI LogHeader()
 {
     HRESULT hr = S_OK;
@@ -761,10 +604,6 @@ extern "C" HRESULT DAPI LogHeader()
 }
 
 
-/********************************************************************
- LogFooterWork - write a standard footer to the log
-
-********************************************************************/
 
 static HRESULT LogFooterWork(
     __in_z __format_string LPCSTR szFormat,
@@ -791,10 +630,6 @@ extern "C" HRESULT DAPI LogFooter()
     return hr;
 }
 
-/********************************************************************
- LogStringWorkRaw - Write a raw, unformatted string to the log
-
-********************************************************************/
 extern "C" HRESULT LogStringWorkRaw(
     __in_z LPCSTR szLogData
     )