@joebigelow / wix-1 / commits / 85735f8b

Move logutil docs into header and standardize inline wrapper methods.

Sean Hall committed Sep 2, 2022 at 16:06 UTC 85735f8b50a9dae190b08abe339aeda7a447a30b
2 files changed +181 -186
src/libs/dutil/WixToolset.DUtil/inc/logutil.h
+181 -21
@@ -24,14 +24,29 @@ typedef HRESULT (DAPI *PFN_LOGSTRINGWORKRAW)(
24 // structs
25
26 // functions
27 +/********************************************************************
28 + IsLogInitialized - Checks if log is currently initialized.
29 +********************************************************************/
30 BOOL DAPI IsLogInitialized();
31
32 +/********************************************************************
33 + IsLogOpen - Checks if log is currently initialized and open.
34 +********************************************************************/
35 BOOL DAPI IsLogOpen();
36
37 +/********************************************************************
38 + LogInitialize - initializes the logutil API
39 +
40 +********************************************************************/
41 void DAPI LogInitialize(
42 __in_opt HMODULE hModule
43 );
44
45 +/********************************************************************
46 + LogOpen - creates an application log file
47 +
48 + NOTE: if wzExt is null then wzLog is path to desired log else wzLog and wzExt are used to generate log name
49 +********************************************************************/
50 HRESULT DAPI LogOpen(
51 __in_z_opt LPCWSTR wzDirectory,
52 __in_z LPCWSTR wzLog,
@@ -42,13 +57,26 @@ HRESULT DAPI LogOpen(
57 __out_z_opt LPWSTR* psczLogPath
58 );
59
60 +/********************************************************************
61 + LogDisable - closes any open files and disables in memory logging.
62 +
63 +********************************************************************/
64 void DAPI LogDisable();
65
66 +/********************************************************************
67 + LogRedirect - Redirects all logging strings to the specified
68 + function - or set NULL to disable the hook
69 +********************************************************************/
70 void DAPI LogRedirect(
71 __in_opt PFN_LOGSTRINGWORKRAW vpfLogStringWorkRaw,
72 __in_opt LPVOID pvContext
73 );
74
75 +/********************************************************************
76 + LogRename - Renames a logfile, moving its contents to a new path,
77 + and re-opening the file for appending at the new
78 + location
79 +********************************************************************/
80 HRESULT DAPI LogRename(
81 __in_z LPCWSTR wzNewPath
82 );
@@ -61,52 +89,119 @@ void DAPI LogUninitialize(
89 __in BOOL fFooter
90 );
91
92 +/********************************************************************
93 + LogIsOpen - returns whether log file is open or note
94 +
95 +********************************************************************/
96 BOOL DAPI LogIsOpen();
97
98 +/********************************************************************
99 + LogSetSpecialParams - sets a special beginline string, endline
100 + string, post-timestamp string, etc.
101 +********************************************************************/
102 HRESULT DAPI LogSetSpecialParams(
103 __in_z_opt LPCWSTR wzSpecialBeginLine,
104 __in_z_opt LPCWSTR wzSpecialAfterTimeStamp,
105 __in_z_opt LPCWSTR wzSpecialEndLine
106 );
107
108 +/********************************************************************
109 + LogSetLevel - sets the logging level
110 +
111 + NOTE: returns previous logging level
112 +********************************************************************/
113 REPORT_LEVEL DAPI LogSetLevel(
114 __in REPORT_LEVEL rl,
115 __in BOOL fLogChange
116 );
117
118 +/********************************************************************
119 + LogGetLevel - gets the current logging level
120 +
121 +********************************************************************/
122 REPORT_LEVEL DAPI LogGetLevel();
123
124 +/********************************************************************
125 + LogGetPath - gets the current log path
126 +
127 +********************************************************************/
128 HRESULT DAPI LogGetPath(
129 __out_ecount_z(cchLogPath) LPWSTR pwzLogPath,
130 __in DWORD cchLogPath
131 );
132
133 +/********************************************************************
134 + LogGetHandle - gets the current log file handle
135 +
136 +********************************************************************/
137 HANDLE DAPI LogGetHandle();
138
86 -HRESULT DAPIV LogString(
87 - __in REPORT_LEVEL rl,
88 - __in_z __format_string LPCSTR szFormat,
89 - ...
90 - );
139 +/********************************************************************
140 + LogStringArgs - implementation of LogString
141
142 +********************************************************************/
143 HRESULT DAPI LogStringArgs(
144 __in REPORT_LEVEL rl,
145 __in_z __format_string LPCSTR szFormat,
146 __in va_list args
147 );
148
98 -HRESULT DAPIV LogStringLine(
149 +/********************************************************************
150 + LogString - write a string to the log
151 +
152 + NOTE: use printf formatting ("%ls", "%d", etc.)
153 +********************************************************************/
154 +inline HRESULT LogString(
155 __in REPORT_LEVEL rl,
156 __in_z __format_string LPCSTR szFormat,
157 ...
102 - );
158 + )
159 +{
160 + HRESULT hr = S_OK;
161 + va_list args;
162 +
163 + va_start(args, szFormat);
164 + hr = LogStringArgs(rl, szFormat, args);
165 + va_end(args);
166
167 + return hr;
168 +}
169 +
170 +/********************************************************************
171 + LogStringLineArgs - implementation of LogStringLine
172 +
173 +********************************************************************/
174 HRESULT DAPI LogStringLineArgs(
175 __in REPORT_LEVEL rl,
176 __in_z __format_string LPCSTR szFormat,
177 __in va_list args
178 );
179
180 +/********************************************************************
181 + LogStringLine - write a string plus LOGUTIL_NEWLINE to the log
182 +
183 + NOTE: use printf formatting ("%ls", "%d", etc.)
184 +********************************************************************/
185 +inline HRESULT LogStringLine(
186 + __in REPORT_LEVEL rl,
187 + __in_z __format_string LPCSTR szFormat,
188 + ...
189 + )
190 +{
191 + HRESULT hr = S_OK;
192 + va_list args;
193 +
194 + va_start(args, szFormat);
195 + hr = LogStringLineArgs(rl, szFormat, args);
196 + va_end(args);
197 +
198 + return hr;
199 +}
200 +
201 +/********************************************************************
202 + LogIdModuleArgs - implementation of LogIdModule
203 +
204 +********************************************************************/
205 HRESULT DAPI LogIdModuleArgs(
206 __in REPORT_LEVEL rl,
207 __in DWORD dwLogId,
@@ -114,31 +209,32 @@ HRESULT DAPI LogIdModuleArgs(
209 __in va_list args
210 );
211
117 -/*
118 - * Wraps LogIdModuleArgs, so inline to save the function call
119 - */
212 +/********************************************************************
213 + LogIdModule - write a string embedded in a MESSAGETABLE in the specified module to the log
214
121 -inline HRESULT LogId(
215 + NOTE: uses format string from MESSAGETABLE resource
216 +********************************************************************/
217 +inline HRESULT LogIdModule(
218 __in REPORT_LEVEL rl,
219 __in DWORD dwLogId,
220 + __in_opt HMODULE hModule,
221 ...
222 )
223 {
224 HRESULT hr = S_OK;
225 va_list args;
226
130 - va_start(args, dwLogId);
131 - hr = LogIdModuleArgs(rl, dwLogId, NULL, args);
227 + va_start(args, hModule);
228 + hr = LogIdModuleArgs(rl, dwLogId, hModule, args);
229 va_end(args);
230
231 return hr;
232 }
233
234 +/********************************************************************
235 + LogIdArgs - inline wrapper for LogIdModuleArgs, passing NULL for hModule
236
138 -/*
139 - * Wraps LogIdModuleArgs, so inline to save the function call
140 - */
141 -
237 +********************************************************************/
238 inline HRESULT LogIdArgs(
239 __in REPORT_LEVEL rl,
240 __in DWORD dwLogId,
@@ -148,18 +244,64 @@ inline HRESULT LogIdArgs(
244 return LogIdModuleArgs(rl, dwLogId, NULL, args);
245 }
246
151 -HRESULT DAPIV LogErrorString(
152 - __in HRESULT hrError,
153 - __in_z __format_string LPCSTR szFormat,
247 +/********************************************************************
248 + LogId - write a string embedded in a MESSAGETABLE in the default module to the log
249 +
250 + NOTE: uses format string from MESSAGETABLE resource
251 +********************************************************************/
252 +inline HRESULT LogId(
253 + __in REPORT_LEVEL rl,
254 + __in DWORD dwLogId,
255 ...
155 - );
256 + )
257 +{
258 + HRESULT hr = S_OK;
259 + va_list args;
260 +
261 + va_start(args, dwLogId);
262 + hr = LogIdArgs(rl, dwLogId, args);
263 + va_end(args);
264 +
265 + return hr;
266 +}
267
268 +/********************************************************************
269 + LogErrorStringArgs - implementation of LogErrorString
270 +
271 +********************************************************************/
272 HRESULT DAPI LogErrorStringArgs(
273 __in HRESULT hrError,
274 __in_z __format_string LPCSTR szFormat,
275 __in va_list args
276 );
277
278 +/********************************************************************
279 + LogErrorString - write an error to the log
280 +
281 + NOTE: use printf formatting ("%ls", "%d", etc.)
282 +********************************************************************/
283 +inline HRESULT LogErrorString(
284 + __in HRESULT hrError,
285 + __in_z __format_string LPCSTR szFormat,
286 + ...
287 + )
288 +{
289 + HRESULT hr = S_OK;
290 +
291 + va_list args;
292 + va_start(args, szFormat);
293 + hr = LogErrorStringArgs(hrError, szFormat, args);
294 + va_end(args);
295 +
296 + return hr;
297 +}
298 +
299 +/********************************************************************
300 + LogErrorIdModule - write an error string embedded in the specified module in a MESSAGETABLE to the log
301 +
302 + NOTE: uses format string from MESSAGETABLE resource
303 + can log no more than three strings in the error message
304 +********************************************************************/
305 HRESULT DAPI LogErrorIdModule(
306 __in HRESULT hrError,
307 __in DWORD dwLogId,
@@ -169,6 +311,12 @@ HRESULT DAPI LogErrorIdModule(
311 __in_z_opt LPCWSTR wzString3
312 );
313
314 +/********************************************************************
315 + LogErrorId - write an error string embedded in the default module in a MESSAGETABLE to the log
316 +
317 + NOTE: uses format string from MESSAGETABLE resource
318 + can log no more than three strings in the error message
319 +********************************************************************/
320 inline HRESULT LogErrorId(
321 __in HRESULT hrError,
322 __in DWORD dwLogId,
@@ -180,10 +328,22 @@ inline HRESULT LogErrorId(
328 return LogErrorIdModule(hrError, dwLogId, NULL, wzString1, wzString2, wzString3);
329 }
330
331 +/********************************************************************
332 + LogHeader - write a standard header to the log
333 +
334 +********************************************************************/
335 HRESULT DAPI LogHeader();
336
337 +/********************************************************************
338 + LogFooter - write a standard footer to the log
339 +
340 +********************************************************************/
341 HRESULT DAPI LogFooter();
342
343 +/********************************************************************
344 + LogStringWorkRaw - Write a raw, unformatted string to the log
345 +
346 +********************************************************************/
347 HRESULT LogStringWorkRaw(
348 __in_z LPCSTR szLogData
349 );
src/libs/dutil/WixToolset.DUtil/logutil.cpp
-165
@@ -65,27 +65,17 @@ static PFN_LOGSTRINGWORKRAW s_vpfLogStringWorkRaw = NULL;
65 static LPVOID s_vpvLogStringWorkRawContext = NULL;
66
67
68 -/********************************************************************
69 - IsLogInitialized - Checks if log is currently initialized.
70 -********************************************************************/
68 extern "C" BOOL DAPI IsLogInitialized()
69 {
70 return LogUtil_fInitializedCriticalSection;
71 }
72
76 -/********************************************************************
77 - IsLogOpen - Checks if log is currently initialized and open.
78 -********************************************************************/
73 extern "C" BOOL DAPI IsLogOpen()
74 {
75 return (INVALID_HANDLE_VALUE != LogUtil_hLog && NULL != LogUtil_sczLogPath);
76 }
77
78
85 -/********************************************************************
86 - LogInitialize - initializes the logutil API
87 -
88 -********************************************************************/
79 extern "C" void DAPI LogInitialize(
80 __in_opt HMODULE hModule
81 )
@@ -100,11 +90,6 @@ extern "C" void DAPI LogInitialize(
90 }
91
92
103 -/********************************************************************
104 - LogOpen - creates an application log file
105 -
106 - NOTE: if wzExt is null then wzLog is path to desired log else wzLog and wzExt are used to generate log name
107 -********************************************************************/
93 extern "C" HRESULT DAPI LogOpen(
94 __in_z_opt LPCWSTR wzDirectory,
95 __in_z LPCWSTR wzLog,
@@ -195,10 +180,6 @@ LExit:
180 }
181
182
198 -/********************************************************************
199 - LogDisable - closes any open files and disables in memory logging.
200 -
201 -********************************************************************/
183 void DAPI LogDisable()
184 {
185 ::EnterCriticalSection(&LogUtil_csLog);
@@ -213,10 +194,6 @@ void DAPI LogDisable()
194 }
195
196
216 -/********************************************************************
217 - LogRedirect - Redirects all logging strings to the specified
218 - function - or set NULL to disable the hook
219 -********************************************************************/
197 void DAPI LogRedirect(
198 __in_opt PFN_LOGSTRINGWORKRAW vpfLogStringWorkRaw,
199 __in_opt LPVOID pvContext
@@ -231,11 +208,6 @@ void DAPI LogRedirect(
208 }
209
210
234 -/********************************************************************
235 - LogRename - Renames a logfile, moving its contents to a new path,
236 - and re-opening the file for appending at the new
237 - location
238 -********************************************************************/
211 HRESULT DAPI LogRename(
212 __in_z LPCWSTR wzNewPath
213 )
@@ -309,20 +281,12 @@ extern "C" void DAPI LogUninitialize(
281 }
282
283
312 -/********************************************************************
313 - LogIsOpen - returns whether log file is open or note
314 -
315 -********************************************************************/
284 extern "C" BOOL DAPI LogIsOpen()
285 {
286 return INVALID_HANDLE_VALUE != LogUtil_hLog;
287 }
288
289
322 -/********************************************************************
323 - LogSetSpecialParams - sets a special beginline string, endline
324 - string, post-timestamp string, etc.
325 -********************************************************************/
290 HRESULT DAPI LogSetSpecialParams(
291 __in_z_opt LPCWSTR wzSpecialBeginLine,
292 __in_z_opt LPCWSTR wzSpecialAfterTimeStamp,
@@ -368,11 +332,6 @@ LExit:
332 return hr;
333 }
334
371 -/********************************************************************
372 - LogSetLevel - sets the logging level
373 -
374 - NOTE: returns previous logging level
375 -********************************************************************/
335 extern "C" REPORT_LEVEL DAPI LogSetLevel(
336 __in REPORT_LEVEL rl,
337 __in BOOL fLogChange
@@ -416,20 +375,12 @@ extern "C" REPORT_LEVEL DAPI LogSetLevel(
375 }
376
377
419 -/********************************************************************
420 - LogGetLevel - gets the current logging level
421 -
422 -********************************************************************/
378 extern "C" REPORT_LEVEL DAPI LogGetLevel()
379 {
380 return LogUtil_rlCurrent;
381 }
382
383
429 -/********************************************************************
430 - LogGetPath - gets the current log path
431 -
432 -********************************************************************/
384 extern "C" HRESULT DAPI LogGetPath(
385 __out_ecount_z(cchLogPath) LPWSTR pwzLogPath,
386 __in DWORD cchLogPath
@@ -451,37 +402,12 @@ LExit:
402 }
403
404
454 -/********************************************************************
455 - LogGetHandle - gets the current log file handle
456 -
457 -********************************************************************/
405 extern "C" HANDLE DAPI LogGetHandle()
406 {
407 return LogUtil_hLog;
408 }
409
410
464 -/********************************************************************
465 - LogString - write a string to the log
466 -
467 - NOTE: use printf formatting ("%ls", "%d", etc.)
468 -********************************************************************/
469 -extern "C" HRESULT DAPIV LogString(
470 - __in REPORT_LEVEL rl,
471 - __in_z __format_string LPCSTR szFormat,
472 - ...
473 - )
474 -{
475 - HRESULT hr = S_OK;
476 - va_list args;
477 -
478 - va_start(args, szFormat);
479 - hr = LogStringArgs(rl, szFormat, args);
480 - va_end(args);
481 -
482 - return hr;
483 -}
484 -
411 extern "C" HRESULT DAPI LogStringArgs(
412 __in REPORT_LEVEL rl,
413 __in_z __format_string LPCSTR szFormat,
@@ -502,27 +428,6 @@ LExit:
428 return hr;
429 }
430
505 -/********************************************************************
506 - LogStringLine - write a string plus LOGUTIL_NEWLINE to the log
507 -
508 - NOTE: use printf formatting ("%ls", "%d", etc.)
509 -********************************************************************/
510 -extern "C" HRESULT DAPIV LogStringLine(
511 - __in REPORT_LEVEL rl,
512 - __in_z __format_string LPCSTR szFormat,
513 - ...
514 - )
515 -{
516 - HRESULT hr = S_OK;
517 - va_list args;
518 -
519 - va_start(args, szFormat);
520 - hr = LogStringLineArgs(rl, szFormat, args);
521 - va_end(args);
522 -
523 - return hr;
524 -}
525 -
431 extern "C" HRESULT DAPI LogStringLineArgs(
432 __in REPORT_LEVEL rl,
433 __in_z __format_string LPCSTR szFormat,
@@ -543,11 +448,6 @@ LExit:
448 return hr;
449 }
450
546 -/********************************************************************
547 - LogIdModuleArgs - write a string embedded in a MESSAGETABLE to the log
548 -
549 - NOTE: uses format string from MESSAGETABLE resource
550 -********************************************************************/
451
452 extern "C" HRESULT DAPI LogIdModuleArgs(
453 __in REPORT_LEVEL rl,
@@ -570,53 +470,6 @@ LExit:
470 return hr;
471 }
472
573 -extern "C" HRESULT DAPI LogIdModule(
574 - __in REPORT_LEVEL rl,
575 - __in DWORD dwLogId,
576 - __in_opt HMODULE hModule,
577 - ...
578 - )
579 -{
580 - AssertSz(REPORT_NONE != rl, "REPORT_NONE is not a valid logging level");
581 - HRESULT hr = S_OK;
582 - va_list args;
583 -
584 - if (REPORT_ERROR != rl && LogUtil_rlCurrent < rl)
585 - {
586 - ExitFunction1(hr = S_FALSE);
587 - }
588 -
589 - va_start(args, hModule);
590 - hr = LogIdWork(rl, (hModule) ? hModule : LogUtil_hModule, dwLogId, args, TRUE);
591 - va_end(args);
592 -
593 -LExit:
594 - return hr;
595 -}
596 -
597 -
598 -
599 -
600 -/********************************************************************
601 - LogError - write an error to the log
602 -
603 - NOTE: use printf formatting ("%ls", "%d", etc.)
604 -********************************************************************/
605 -extern "C" HRESULT DAPIV LogErrorString(
606 - __in HRESULT hrError,
607 - __in_z __format_string LPCSTR szFormat,
608 - ...
609 - )
610 -{
611 - HRESULT hr = S_OK;
612 -
613 - va_list args;
614 - va_start(args, szFormat);
615 - hr = LogErrorStringArgs(hrError, szFormat, args);
616 - va_end(args);
617 -
618 - return hr;
619 -}
473
474 extern "C" HRESULT DAPI LogErrorStringArgs(
475 __in HRESULT hrError,
@@ -648,12 +501,6 @@ LExit:
501 }
502
503
651 -/********************************************************************
652 - LogErrorIdModule - write an error string embedded in a MESSAGETABLE to the log
653 -
654 - NOTE: uses format string from MESSAGETABLE resource
655 - can log no more than three strings in the error message
656 -********************************************************************/
504 extern "C" HRESULT DAPI LogErrorIdModule(
505 __in HRESULT hrError,
506 __in DWORD dwLogId,
@@ -681,10 +528,6 @@ LExit:
528 return hr;
529 }
530
684 -/********************************************************************
685 - LogHeader - write a standard header to the log
686 -
687 -********************************************************************/
531 extern "C" HRESULT DAPI LogHeader()
532 {
533 HRESULT hr = S_OK;
@@ -761,10 +604,6 @@ extern "C" HRESULT DAPI LogHeader()
604 }
605
606
764 -/********************************************************************
765 - LogFooterWork - write a standard footer to the log
766 -
767 -********************************************************************/
607
608 static HRESULT LogFooterWork(
609 __in_z __format_string LPCSTR szFormat,
@@ -791,10 +630,6 @@ extern "C" HRESULT DAPI LogFooter()
630 return hr;
631 }
632
794 -/********************************************************************
795 - LogStringWorkRaw - Write a raw, unformatted string to the log
796 -
797 -********************************************************************/
633 extern "C" HRESULT LogStringWorkRaw(
634 __in_z LPCSTR szLogData
635 )