From 85735f8b50a9dae190b08abe339aeda7a447a30b Mon Sep 17 00:00:00 2001 From: Sean Hall Date: Fri, 2 Sep 2022 16:06:53 -0500 Subject: Move logutil docs into header and standardize inline wrapper methods. --- src/libs/dutil/WixToolset.DUtil/inc/logutil.h | 202 +++++++++++++++++++++++--- src/libs/dutil/WixToolset.DUtil/logutil.cpp | 165 --------------------- 2 files changed, 181 insertions(+), 186 deletions(-) (limited to 'src') 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 ) -- cgit v1.2.3-55-g6feb