WinMFCBackupEvents.cpp

#include "stdafx.h"

#include <stdio.h>
#include <string.h>

#include "WinMFCApp.h"
#include "Common.h"
#include "CommonBackupEvents.h"
#include "CommonSelfTest.h"
#include "WinMFCTaskbarList.h"

// Top Level Functions

// void ScreenLogActivity(WVBString Message);
// void ScreenLogActivityIndented(WVBString Message);
// void ScreenLogError(WVBString Message);
// void ScreenLogWarning(WVBString Message);
// void ReplaceActivityProgressLine(WVBString Message);
// void RemoveLineFromErrorLog(WVBString LineToRemove);
// void DisplayTheCurrentFolderForWindows(WVBString Folder, int Force = false);
// void UpdateActivityProgress(double PercentDone, int Flags);
// void SetProgressBarPos(int Position);
// int  BackupGetProgressBarPos();
// void SetProgressBarRange(int Min, int Max);
// void BackupSetTaskbarError();
// void SetTaskbarNoProgress();
// void SetTaskbarProgressValue(int Position);
// void EnableOrDisableViewLogLinkDependingOnStatus();
// void EnableOrDisableButtonsDependingOnStatus();
// void SetHourglass(int Enabled);
// int  BackupPromptYesNo(const wchar_t *Message);

// Helper Functions

#ifdef SHOW_TIME_STAMP
static WVBString AddTimeStamp(WVBString Message);
static VBString AddUTF8TimeStamp(VBString Message);
#endif
static int BackgroundTrashCleanupHelperIsRunning();
static int BackgroundTrashCleanupConsoleIsAvailable();
#ifdef ENABLE_SELF_TEST_LOGIC
static int AutoSelfTestConsoleIsAvailable();
static void ClearConsoleProgressLine();
static void UTF8ShowConsoleProgressLine(VBString UTF8Text);
static VBString UTF8FormatConsoleDeleteProgressLine(double ItemsDeleted);
static int ConsoleLineIsDeleteProgressBase(WVBString Message);
#endif

// External Helper Functions

int GetWindowTextLengthUnicode(CWnd &Wnd);
void ReplaceSelectedTextUnicode(CWnd &Wnd, const wchar_t *Text);
int GetEditLineIndex(CWnd &Wnd, int Line);
int GetEditLineFromChar(CWnd &Wnd, int CharIndex);
void SetEditSelection(CWnd &Wnd, int Start, int End);

// Globals

#ifdef ENABLE_SELF_TEST_LOGIC
static int gConsoleProgressLineVisible = false;
static size_t gConsoleProgressLineLength = 0;
// The Windows GUI is wide-character.  These UTF-8 byte strings are only for
// the optional debug/self-test console, where progress is repainted with
// printf() instead of written to an MFC control.
static VBString gUTF8ConsoleDeleteProgressBase;
#endif

// External Globals

extern CFastBackupApp gTheApp;
extern CSafeTaskbarList gTaskBarList;
extern int gErrorCount, gWarningCount;
extern int gBackgroundFastBackupTrashFolderCleanup;
extern int gCommandLineMode;
extern CRITICAL_SECTION LogActivityCriticalSection;
extern int gActivityProgressTextStart;
extern int gActivityProgressTextEnd;
extern int gActivityProgressLineStart;
extern VBString gActivityProgressLastText;


// Top Level Functions

// Writes backup activity to the correct Windows-facing destination.  Normal GUI
// backups go to the activity log; background cleanup and automated self-tests
// may instead write to an optional console or suppress UI updates entirely.
void ScreenLogActivity(WVBString Message)
{
#ifdef DISPLAY_TRASH_CLEANUP
	// The background cleanup debug mode has no dialog, so write directly to its
	// console when one is available.
	if (BackgroundTrashCleanupConsoleIsAvailable())
	{
#ifdef SHOW_TIME_STAMP
		Message = AddTimeStamp(Message);
#endif
		printf("%s\n", WVBStringToVBString(Message).Buffer);
		return;
	}
#endif

	// Hidden background cleanup must not touch the dialog because the dialog has
	// not been created in that helper process path.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

#ifdef ENABLE_SELF_TEST_LOGIC
	// Automated self-tests launched through the GUI executable report to the
	// console so batch files can see progress without opening the GUI log.
	if (AutoSelfTestConsoleIsAvailable())
	{
		VBString UTF8Message;

		// Clear any in-place delete progress before printing a normal line.
		UTF8Message = WideToUTF8(Message);
		ClearConsoleProgressLine();

		// Some delete/cleanup lines become the base text for later in-place item
		// count updates; they are stored but not printed until progress arrives.
		if (ConsoleLineIsDeleteProgressBase(Message))
#ifdef SHOW_TIME_STAMP
			gUTF8ConsoleDeleteProgressBase = AddUTF8TimeStamp(UTF8Message);
#else
			gUTF8ConsoleDeleteProgressBase = UTF8Message;
#endif
		else
		{
			// A normal activity line cancels any pending delete-progress base and
			// is printed immediately.
			gUTF8ConsoleDeleteProgressBase = "";
#ifdef SHOW_TIME_STAMP
			UTF8Message = AddUTF8TimeStamp(UTF8Message);
#endif
			printf("%s\n", UTF8Message.Buffer);
		}
		return;
	}
#endif

	// Normal GUI logging: optionally timestamp the wide text and append it to
	// the main dialog activity log.
#ifdef SHOW_TIME_STAMP
	Message = AddTimeStamp(Message);
#endif
	gTheApp.m_MainDlg->LogActivityMessage(Message);
}


// Writes an indented activity line.  This keeps call sites simple while routing
// through ScreenLogActivity() so console/helper/timestamp handling remains in
// one place.
void ScreenLogActivityIndented(WVBString Message)
{
	// Prefix with four spaces to match the existing nested activity-log style.
	ScreenLogActivity((WVBString)L"    " + Message);
}


// Writes a backup error to the correct destination and records that the current
// run has an error.  Normal GUI errors also turn the taskbar progress state red.
void ScreenLogError(WVBString Message)
{
	// Count the error even when the visible destination is a console or hidden
	// helper path.
	gErrorCount++;
#ifdef DISPLAY_TRASH_CLEANUP
	// Optional background-cleanup debug output goes to stderr.
	if (BackgroundTrashCleanupConsoleIsAvailable())
	{
#ifdef SHOW_TIME_STAMP
		Message = AddTimeStamp(Message);
#endif
		fprintf(stderr, "%s\n", WVBStringToVBString(Message).Buffer);
		return;
	}
#endif

	// Hidden cleanup helpers cannot display dialog errors.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

#ifdef ENABLE_SELF_TEST_LOGIC
	// Automated self-test errors go to stderr after clearing any in-place
	// progress line.
	if (AutoSelfTestConsoleIsAvailable())
	{
		VBString UTF8Message;

		UTF8Message = WideToUTF8(Message);
		ClearConsoleProgressLine();
#ifdef SHOW_TIME_STAMP
		UTF8Message = AddUTF8TimeStamp(UTF8Message);
#endif
		fprintf(stderr, "%s\n", UTF8Message.Buffer);
		return;
	}
#endif

	// Normal GUI errors are shown in the error log and reflected in the taskbar.
#ifdef SHOW_TIME_STAMP
	Message = AddTimeStamp(Message);
#endif
	gTheApp.m_MainDlg->LogErrorMessage(Message);
	BackupSetTaskbarError();
}


// Writes a backup warning to the same visible destination as errors, but records
// it separately so summaries can distinguish warnings from failures.
void ScreenLogWarning(WVBString Message)
{
	// Count the warning regardless of which UI/output route is active.
	gWarningCount++;
#ifdef DISPLAY_TRASH_CLEANUP
	// Optional background-cleanup debug output goes to stderr with errors.
	if (BackgroundTrashCleanupConsoleIsAvailable())
	{
#ifdef SHOW_TIME_STAMP
		Message = AddTimeStamp(Message);
#endif
		fprintf(stderr, "%s\n", WVBStringToVBString(Message).Buffer);
		return;
	}
#endif

	// Hidden cleanup helpers suppress UI output.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

#ifdef ENABLE_SELF_TEST_LOGIC
	// Automated self-test warnings go to stderr so they are visible in the
	// launching console.
	if (AutoSelfTestConsoleIsAvailable())
	{
		VBString UTF8Message;

		UTF8Message = WideToUTF8(Message);
		ClearConsoleProgressLine();
#ifdef SHOW_TIME_STAMP
		UTF8Message = AddUTF8TimeStamp(UTF8Message);
#endif
		fprintf(stderr, "%s\n", UTF8Message.Buffer);
		return;
	}
#endif

	// In the GUI, warnings share the error log but do not force taskbar error
	// state.
#ifdef SHOW_TIME_STAMP
	Message = AddTimeStamp(Message);
#endif
	gTheApp.m_MainDlg->LogErrorMessage(Message);
}


// Replaces the current activity progress line with a new message.  This is used
// for visible progress text that should update in place rather than append a new
// activity-log row each time.
void ReplaceActivityProgressLine(WVBString Message)
{
#ifdef DISPLAY_TRASH_CLEANUP
	// The cleanup debug console cannot edit the MFC log, so print a full line.
	if (BackgroundTrashCleanupConsoleIsAvailable())
	{
#ifdef SHOW_TIME_STAMP
		Message = AddTimeStamp(Message);
#endif
		printf("%s\n", WVBStringToVBString(Message).Buffer);
		return;
	}
#endif

	// Hidden cleanup helpers have no visible progress line to replace.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

#ifdef ENABLE_SELF_TEST_LOGIC
	// The automated self-test console path reuses normal activity logging.
	if (AutoSelfTestConsoleIsAvailable())
	{
		ScreenLogActivity(Message);
		return;
	}
#endif

#ifdef SHOW_TIME_STAMP
	Message = AddTimeStamp(Message);
#endif

	// Normal GUI path replaces the current activity-progress line in the dialog.
	gTheApp.m_MainDlg->ReplaceActivityProgressLine(Message);
}


// Leaves the current transient activity row visible as an ordinary completed
// log row.  A later transient update will then append beneath it.
void FinishActivityProgressLine()
{
	EnterCriticalSection(&LogActivityCriticalSection);
	gActivityProgressTextStart = -1;
	gActivityProgressTextEnd = -1;
	gActivityProgressLineStart = -1;
	gActivityProgressLastText = "";
	LeaveCriticalSection(&LogActivityCriticalSection);
}


// Removes a line from the visible error log after the related condition has been
// resolved.  This is a GUI-only operation; console output is historical text and
// cannot be removed.
void RemoveLineFromErrorLog(WVBString LineToRemove)
{
	// Background cleanup has no MFC error log to edit.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// Delegate the actual rich-edit manipulation to the main dialog.
	gTheApp.m_MainDlg->RemoveLineFromErrorLog(LineToRemove);
}


// Updates the current-folder field shown while a backup is running.  Normal
// scan-only updates may be throttled by the dialog to avoid flicker, but callers
// can force the update when the folder is about to be used for real file work.
void DisplayTheCurrentFolderForWindows(WVBString Folder, int Force)
{
	// Background cleanup runs before the dialog exists.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// Show the folder currently being scanned or copied.
	gTheApp.m_MainDlg->UpdateCurrentFolder(Folder, Force);
}


// Windows adapter for transient activity progress updates.  It handles big-file
// copy percentages, cleanup/delete item counts, and the text field that appears
// in the activity log beside the current operation.
void UpdateActivityProgress(double PercentDone, int Flags)
{
	VBString PercentDoneTemp;
	WVBString WPercentDoneTemp;
	int Length, SelectionLength;

#ifdef DISPLAY_TRASH_CLEANUP
	// The optional cleanup debug console only needs delete item counts.
	if (BackgroundTrashCleanupConsoleIsAvailable())
	{
		if (Flags & DELETING_ITEMS_WITHOUT_TOTAL)
		{
			if (PercentDone == EMPTY_FOLDER_START) PercentDone = 0.0;
			if (PercentDone >= 0)
				printf("Deleting items  (%4.0f Items)\r", PercentDone);
		}
		return;
	}
#endif

	// Hidden cleanup helpers have no dialog progress controls.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

#ifdef ENABLE_SELF_TEST_LOGIC
	// Automated self-test console progress is only used for delete item counts;
	// other transient GUI progress is intentionally suppressed.
	if (AutoSelfTestConsoleIsAvailable())
	{
		if (Flags & DELETING_ITEMS_WITHOUT_TOTAL)
		{
			VBString UTF8Text;

			if (PercentDone == EMPTY_FOLDER_START) PercentDone = 0.0;
			if (PercentDone < 0) return;

			// Repaint the console line with the latest item count.
			UTF8Text = UTF8FormatConsoleDeleteProgressLine(PercentDone);
			UTF8ShowConsoleProgressLine(UTF8Text);
		}
		return;
	}
#endif

	// Command-line mode has no dialog progress fields to update.
	if (gCommandLineMode) return;

	// Ignore progress callbacks that are not one of the visible progress styles
	// handled by this adapter.
	if ((Flags & (ACTIVITY_PROGRESS_PERCENT | DELETING_ITEMS_WITHOUT_TOTAL)) == false
		&& PercentDone != EMPTY_FOLDER_START
		&& PercentDone != EMPTY_FOLDER_DONE
		&& PercentDone != EMPTY_FOLDER_DONE_2) return;

	// Format big-file copy percentages.  Do not append a newline because this
	// text replaces part of the current activity line inside the rich edit.
	if (Flags & ACTIVITY_PROGRESS_PERCENT_3_DECIMALS)
	{
		PercentDoneTemp.Format("% 3.3f%%", PercentDone);
		while (PercentDoneTemp.Length < 8) PercentDoneTemp = " " + PercentDoneTemp;
		SelectionLength = 8;
	}
	else if (Flags & ACTIVITY_PROGRESS_PERCENT_2_DECIMALS)
	{
		PercentDoneTemp.Format("% 3.2f%%", PercentDone);
		while (PercentDoneTemp.Length < 7) PercentDoneTemp = " " + PercentDoneTemp;
		SelectionLength = 7;
	}
	else if (Flags & ACTIVITY_PROGRESS_PERCENT_1_DECIMAL)
	{
		PercentDoneTemp.Format("% 3.1f%%", PercentDone);
		while (PercentDoneTemp.Length < 6) PercentDoneTemp = " " + PercentDoneTemp;
		SelectionLength = 6;
	}
	else if (Flags & ACTIVITY_PROGRESS_PERCENT)
	{
		PercentDoneTemp.Format("% 3.0f%%", PercentDone);
		while (PercentDoneTemp.Length < 4) PercentDoneTemp = " " + PercentDoneTemp;
		SelectionLength = 4;
	}

	// Format cleanup/delete item counts.  These append after a delete message
	// rather than replacing a fixed-width percentage field.
	if (Flags & DELETING_ITEMS_WITHOUT_TOTAL)
	{
		if (PercentDone == EMPTY_FOLDER_START)
			PercentDoneTemp = "  (0 Items)";
		else
			PercentDoneTemp.Format("  (%.0f Items)", PercentDone);
		SelectionLength = 0;
	}

	// Convert file-copy sentinel values into short visible status text.
	if ((Flags & DELETING_ITEMS_WITHOUT_TOTAL) == false && PercentDone == FILE_COPY_ABORTED) PercentDoneTemp = " ABORTED";
	if ((Flags & DELETING_ITEMS_WITHOUT_TOTAL) == false && PercentDone == FILE_COPY_FAILED) PercentDoneTemp = " FAILED";

	// Use compact completion text for common finished states.
	if ((Flags & DELETING_ITEMS_WITHOUT_TOTAL) == false && PercentDone == 100.0) PercentDoneTemp = " 100%";
	if (PercentDone == EMPTY_FOLDER_START && (Flags & DELETING_ITEMS_WITHOUT_TOTAL) == false) {
		PercentDoneTemp = "   0%";
		SelectionLength = 0;
	}
	if (PercentDone == EMPTY_FOLDER_DONE) PercentDoneTemp = " Done";
	if (PercentDone == EMPTY_FOLDER_DONE_2) PercentDoneTemp = " done";

	// Replace the same progress field each time.  The old code selected the
	// last N characters using the new text width, which could leave old
	// percentage text behind or append repeatedly when the width changed.
	EnterCriticalSection(&LogActivityCriticalSection);

	// Read the current activity-log length while holding the log lock so the
	// saved selection range cannot race another log write.
	Length = GetWindowTextLengthUnicode(gTheApp.m_MainDlg->m_ActivityLog);

	// Rebuild the selection range if the saved range is invalid for the current
	// rich-edit contents.  This normally happens at the start of a new progress
	// line or after the log has been cleared.
	if (   gActivityProgressTextStart < 0
		|| gActivityProgressTextEnd < gActivityProgressTextStart
		|| gActivityProgressTextEnd > Length)
	{
		gActivityProgressTextEnd = Length;
		gActivityProgressTextStart = Length - SelectionLength;
		if (gActivityProgressTextStart < 0) gActivityProgressTextStart = 0;

		// Remember the start of the line containing the progress field so other
		// activity-log code can keep replacing within the same visible row.
		gActivityProgressLineStart = GetEditLineIndex(gTheApp.m_MainDlg->m_ActivityLog, GetEditLineFromChar(gTheApp.m_MainDlg->m_ActivityLog, gActivityProgressTextStart));
		if (gActivityProgressLineStart < 0) gActivityProgressLineStart = gActivityProgressTextStart;
	}

	// Avoid repainting the rich edit when the visible progress text has not
	// changed; this reduces flicker and keeps the selection stable.
	if (gActivityProgressLastText == PercentDoneTemp && gActivityProgressTextEnd <= Length)
	{
		LeaveCriticalSection(&LogActivityCriticalSection);
		return;
	}

	// Select the old progress text and replace it with the new wide text.
	SetEditSelection(gTheApp.m_MainDlg->m_ActivityLog, gActivityProgressTextStart, gActivityProgressTextEnd);
	WPercentDoneTemp = PercentDoneTemp;
	ReplaceSelectedTextUnicode(gTheApp.m_MainDlg->m_ActivityLog, WPercentDoneTemp);

	// Save the new selection end and text so the next update replaces the same
	// field and can skip duplicate repaint requests.
	gActivityProgressTextEnd = gActivityProgressTextStart + PercentDoneTemp.Length;
	gActivityProgressLastText = PercentDoneTemp;
	LeaveCriticalSection(&LogActivityCriticalSection);
}


// Sets the dialog progress-bar position.
void SetProgressBarPos(int Position)
{
	// Background cleanup has no progress bar.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// Forward the position to the main dialog progress control.
	gTheApp.m_MainDlg->m_ProgressBar.SetPos(Position);
}


// Returns the dialog progress-bar position.
int BackupGetProgressBarPos()
{
	// Helper mode has no dialog, so report a neutral progress position.
	if (BackgroundTrashCleanupHelperIsRunning()) return 0;

	// Ask the main dialog progress control for the current position.
	return gTheApp.m_MainDlg->m_ProgressBar.GetPos();
}


// Sets the range used by the dialog progress bar.
void SetProgressBarRange(int Min, int Max)
{
	// Background cleanup has no progress bar to configure.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// Use the 32-bit range API because backup progress can cover many files.
	gTheApp.m_MainDlg->m_ProgressBar.SetRange32(Min, Max);
}


// Marks the Windows taskbar progress indicator as an error.
void BackupSetTaskbarError()
{
	// Background cleanup has no main window or taskbar progress button.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// Show the Windows taskbar progress state as failed.
	gTaskBarList->SetProgressState(gTheApp.m_MainDlg->GetSafeHwnd(), TBPF_ERROR);
}


// Clears the Windows taskbar progress indicator.
void SetTaskbarNoProgress()
{
	// Background cleanup has no main window or taskbar progress button.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// Remove any active taskbar progress state from the main window.
	gTaskBarList->SetProgressState(gTheApp.m_MainDlg->GetSafeHwnd(), TBPF_NOPROGRESS);
}


// Updates the Windows taskbar progress indicator.
void SetTaskbarProgressValue(int Position)
{
	// Background cleanup has no main window or taskbar progress button.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// The taskbar progress helper always uses a 0-100 range.
	gTaskBarList->SetProgressValue(gTheApp.m_MainDlg->GetSafeHwnd(), Position, 100);
}


// Enables or disables clickable log links on the main dialog.
void EnableOrDisableViewLogLinkDependingOnStatus()
{
	// Background cleanup has no visible links.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// Let the dialog decide which log links are currently valid.
	gTheApp.m_MainDlg->EnableOrDisableViewLogLinkDependingOnStatus();
}


// Enables or disables the main dialog controls while a backup is running.
void EnableOrDisableButtonsDependingOnStatus()
{
	// Background cleanup has no visible controls.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// Let the main dialog apply its normal running/idle button state.
	gTheApp.m_MainDlg->EnableOrDisableButtonsDependingOnStatus();
}


// Turns the main dialog hourglass cursor on or off.
void SetHourglass(int Enabled)
{
	// Background cleanup has no dialog cursor to update.
	if (BackgroundTrashCleanupHelperIsRunning()) return;

	// Store the cursor state on the dialog; cursor handlers read this flag.
	gTheApp.m_MainDlg->DisplayHourglass = Enabled;

	// Force Windows to ask for the cursor again immediately.
	::SendMessage(gTheApp.m_MainDlg->GetSafeHwnd(), WM_SETCURSOR, 0, 0);
}


// Displays a shared Yes/No prompt as a Windows message box.  This is the GUI
// equivalent of the console prompt used by the CLI build.
int BackupPromptYesNo(const wchar_t *Message)
{
	// Default to No to keep destructive or surprising operations conservative.
	return AfxMessageBox(Message, MB_YESNO | MB_ICONQUESTION | MB_DEFBUTTON2) == IDYES;
}


// Helper Functions

#ifdef SHOW_TIME_STAMP
// Adds a local timestamp to a wide activity/error message when timestamp output
// is enabled.  The special clear marker must pass through untouched because it
// is a command to the UI log rather than visible text.
static WVBString AddTimeStamp(WVBString Message)
{
	SYSTEMTIME Time;
	wchar_t TimeStamp[24];

	// Empty messages and the log-clear sentinel should not gain a timestamp.
	if (Message == L"" || Message == L"##CLEAR##") return Message;

	// Format to millisecond precision so fast self-test and cleanup events are
	// easier to order when diagnosing timing-sensitive behaviour.
	GetLocalTime(&Time);
	swprintf_s(TimeStamp, sizeof(TimeStamp) / sizeof(TimeStamp[0]), L"%02d:%02d:%02d.%03d  ", Time.wHour, Time.wMinute, Time.wSecond, Time.wMilliseconds);
	return (WVBString)TimeStamp + Message;
}


// Adds a local timestamp to UTF-8 console text.  This mirrors AddTimeStamp()
// for the optional self-test/debug console path.
static VBString AddUTF8TimeStamp(VBString Message)
{
	SYSTEMTIME Time;
	VBString TimeStamp;

	// Keep blank console lines blank.
	if (Message == "") return Message;

	// Use the same display format as the wide UI log timestamp.
	GetLocalTime(&Time);
	TimeStamp.Format("%02d:%02d:%02d.%03d  ", Time.wHour, Time.wMinute, Time.wSecond, Time.wMilliseconds);
	return TimeStamp + Message;
}
#endif


// Returns true while the background trash-cleanup helper is running before the
// MFC dialog exists.  Most UI events must be ignored in that mode.
static int BackgroundTrashCleanupHelperIsRunning()
{
	return gBackgroundFastBackupTrashFolderCleanup;
}


// Returns true when the background cleanup helper has an optional debug console
// available.  In that mode log text goes to printf()/fprintf() instead of MFC.
static int BackgroundTrashCleanupConsoleIsAvailable()
{
#ifdef DISPLAY_TRASH_CLEANUP
	// Only use the console when this helper mode is active and Windows has a
	// console window attached to the process.
	return BackgroundTrashCleanupHelperIsRunning() && GetConsoleWindow() != NULL;
#else
	// In normal builds the hidden helper produces no UI output.
	return false;
#endif
}

#ifdef ENABLE_SELF_TEST_LOGIC
// Returns true for automated GUI-executable self-tests that are reporting to a
// console instead of the MFC activity log.
static int AutoSelfTestConsoleIsAvailable()
{
	return gSelfTestRequested && !gSelfTestInteractive && GetConsoleWindow() != NULL;
}


// Clears an in-place console progress line before printing a normal log line.
// This prevents the next newline output from being mixed with the carriage
// return progress repaint text.
static void ClearConsoleProgressLine()
{
	size_t i;

	// Nothing has been painted in place yet.
	if (!gConsoleProgressLineVisible) return;

	// Overwrite the previous progress text with spaces and return to column 0.
	printf("\r");
	for (i = 0; i < gConsoleProgressLineLength; i++)
		printf(" ");
	printf("\r");
	fflush(stdout);

	// The console is now back to a clean line.
	gConsoleProgressLineVisible = false;
	gConsoleProgressLineLength = 0;
}


// Repaints a UTF-8 progress line in-place in the console.  Any leftover
// characters from a previous longer line are cleared with trailing spaces.
static void UTF8ShowConsoleProgressLine(VBString UTF8Text)
{
	size_t Length, i;

	// Print the replacement text at the start of the current console line.
	Length = UTF8Text.Length;
	printf("\r%s", UTF8Text.Buffer);

	// Clear old characters when the new progress text is shorter.
	for (i = Length; i < gConsoleProgressLineLength; i++)
		printf(" ");
	fflush(stdout);

	// Remember the width so the next repaint can clear any leftover characters.
	gConsoleProgressLineVisible = true;
	gConsoleProgressLineLength = Length;
}


// Formats the automated self-test console line used while deleting trash/OLD
// folders.  The base text is captured from the most recent matching log line so
// the changing item count can be repainted on the same console row.
static VBString UTF8FormatConsoleDeleteProgressLine(double ItemsDeleted)
{
	char ItemText[40];
	VBString UTF8Text;

	// Negative values are internal sentinels; the console display starts at 0.
	if (ItemsDeleted < 0.0)
		ItemsDeleted = 0.0;

	// Keep the item count fixed-width so the in-place repaint stays tidy.
	sprintf_s(ItemText, sizeof(ItemText), "  (%4.0f Items)", ItemsDeleted);
	if (gUTF8ConsoleDeleteProgressBase == "")
	{
		// Fall back to the generic trash text when no specific base line has
		// been captured yet.
		UTF8Text = "Deleting _Fast-Backup-Trash";
		UTF8Text += ItemText;
		return UTF8Text;
	}

	// Append the live item count to the captured delete/cleanup line.
	UTF8Text = gUTF8ConsoleDeleteProgressBase;
	UTF8Text += ItemText;
	return UTF8Text;
}


// Detects activity lines that should become the base text for a later in-place
// delete progress update on the automated self-test console.
static int ConsoleLineIsDeleteProgressBase(WVBString Message)
{
	VBString UTF8Message;

	// Trim and convert once so the prefix checks match the console text.
	UTF8Message = WideToUTF8(Message.Trim());
	return UTF8TextStartsWith(UTF8Message, "Deleting previous Fast-Backup OLD folder ")
		|| UTF8TextStartsWith(UTF8Message, "Deleting Old folder ")
		|| UTF8TextStartsWith(UTF8Message, "Cleaning Old folder ")
		|| UTF8TextStartsWith(UTF8Message, "Deleting _Fast-Backup-Trash")
		|| UTF8TextStartsWith(UTF8Message, "Deleting Recycling Bin")
		|| UTF8TextStartsWith(UTF8Message, "Deleting folder ");
}
#endif