HiddenDesktop.cs

// =============================================================================
// GPAL - Generally Positive Automation Library
// Copyright © 2026 Software Decisions, Inc. All rights reserved.
//
// This file is part of GPAL.
// Licensed under the Business Source License 1.1
//
// Primary development, architecture, and vision by Michael B. Vederman,
// CEO of Software Decisions, Inc., Texas.
//
// Internal development maintained privately.
// Public releases appear on GitHub: https://github.com/SoftwareDecisionsInc/GPAL.
//
// See LICENSE for full terms, including Additional Use Grant.
// =============================================================================
 
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Diagnostics;
using System.Drawing;
using System.Linq;
using System.Runtime.ExceptionServices;
using System.Runtime.InteropServices;
using System.Threading;
using System.Windows.Forms;
using static GenerallyPositive.Enums;
 
namespace GenerallyPositive.Browser
{
    public static class HiddenDesktop
    {
        private const uint GenericAll = 0x10000000;
        private const uint DesktopSwitchDesktop = 0x0100;

        public const string DefaultName = "GPAL.Hidden";

        internal const int DefaultPeekMs = 5_000;
 
        // by name, in the order they were made, which is the order Peek walks them in
        private static readonly Dictionary<string, IntPtr> desktops = new Dictionary<string, IntPtr>();
        private static readonly object gate = new object();
 
        // how many desktops have been handed out to browsers that did not name one
        private static int unnamed = 0;
 
        // the desktop the screen was on before a peek switched away from it, and the only handle that can put it
        // back. zero when the screen is where the user left it
        private static IntPtr cameFrom = IntPtr.Zero;
 
        private delegate bool EnumDesktopWindowsProc(IntPtr hWnd, IntPtr lParam);
 
        // the screen is not the process's to keep. a peek still running when the process ends, or when an
        // exception takes the process down, hands the screen back on the way out rather than leaving somebody
        // looking at a desktop with nothing on it to leave by
        static HiddenDesktop()
        {
            AppDomain.CurrentDomain.ProcessExit += (sender, args) => Return();
            AppDomain.CurrentDomain.UnhandledException += (sender, args) => Return();
        }
 
        [DllImport("user32.dll", SetLastError = true, CharSet = CharSet.Unicode)]
        private static extern IntPtr CreateDesktop(string lpszDesktop, IntPtr lpszDevice, IntPtr pDevmode, int dwFlags, uint dwDesiredAccess, IntPtr lpsa);
 
        [DllImport("user32.dll", SetLastError = true)]
        private static extern bool SetThreadDesktop(IntPtr hDesktop);
 
        [DllImport("user32.dll", SetLastError = true)]
        private static extern bool CloseDesktop(IntPtr hDesktop);
 
        [DllImport("user32.dll", SetLastError = true)]
        private static extern bool EnumDesktopWindows(IntPtr hDesktop, EnumDesktopWindowsProc lpfn, IntPtr lParam);
 
        [DllImport("user32.dll")]
        private static extern bool IsWindowVisible(IntPtr hWnd);
 
        [DllImport("user32.dll", SetLastError = true)]
        private static extern bool SwitchDesktop(IntPtr hDesktop);
 
        [DllImport("user32.dll", SetLastError = true)]
        private static extern IntPtr OpenInputDesktop(uint dwFlags, bool fInherit, uint dwDesiredAccess);
 
        [DllImport("user32.dll", SetLastError = true)]
        private static extern bool RegisterHotKey(IntPtr hWnd, int id, uint fsModifiers, uint vk);
 
        [DllImport("user32.dll", SetLastError = true)]
        private static extern bool UnregisterHotKey(IntPtr hWnd, int id);

        internal static string StartupNameFor(string name)
        {
            return $@"WinSta0\{name}";
        }

        internal static string NextName()
        {
            return $"{DefaultName}.{Interlocked.Increment(ref unnamed)}";
        }

        internal static IReadOnlyList<string> Names
        {
            get
            {
                lock (gate)
                    return desktops.Keys.ToList();
            }
        }

        internal static bool Ensure(string name)
        {
            bool retVal;
 
            lock (gate)
            {
                if (false == desktops.ContainsKey(name))
                {
                    IntPtr made = CreateDesktop(name, IntPtr.Zero, IntPtr.Zero, 0, GenericAll, IntPtr.Zero);
 
                    if (IntPtr.Zero == made)
                        GPAL.PublishSimpleEvent(GPALEventType.EXCEPTION, $"Could not make the desktop [{name}]", null, GPALObjectType.Browser,
                            new Win32Exception(Marshal.GetLastWin32Error()));
                    else
                        desktops[name] = made;
                }
 
                retVal = true == desktops.ContainsKey(name);
            }
 
            return retVal;
        }

        internal static T Launch<T>(string name, Func<T> launch)
        {
            T retVal = default(T);
            ExceptionDispatchInfo failure = null;
            IntPtr handle = HandleFor(name);
 
            Thread launcher = new Thread(() =>
            {
                if (false == SetThreadDesktop(handle))
                    failure = ExceptionDispatchInfo.Capture(
                        new Win32Exception(Marshal.GetLastWin32Error(), $"Could not put the launching thread on [{name}]"));
                else
                {
                    // caught to be rethrown on the workflow's own thread, so a launch that failed fails where it
                    // was asked for rather than on a thread nobody is holding
                    try
                    {
                        retVal = launch();
                    }
                    catch (Exception ex)
                    {
                        failure = ExceptionDispatchInfo.Capture(ex);
                    }
                }
            });
 
            launcher.IsBackground = true;
            launcher.Start();
            launcher.Join();
 
            failure?.Throw();
 
            return retVal;
        }

        internal static int WindowCount(string name)
        {
            int retVal = 0;
            IntPtr handle = HandleFor(name);
 
            if (IntPtr.Zero != handle)
                EnumDesktopWindows(handle, (window, param) =>
                {
                    if (true == IsWindowVisible(window))
                        retVal++;
 
                    return true;
                }, IntPtr.Zero);
 
            return retVal;
        }

        internal static int WindowCount()
        {
            return Names.Sum(name => WindowCount(name));
        }

        internal static bool HasWindows(string name, int timeoutInMs)
        {
            bool retVal = false;
            DateTime giveUpAt = DateTime.Now.AddMilliseconds(timeoutInMs);
 
            while (false == retVal && DateTime.Now < giveUpAt)
            {
                retVal = 0 < WindowCount(name);
 
                if (false == retVal)
                    Thread.Sleep(250);
            }
 
            return retVal;
        }

        internal static bool IsShowing
        {
            get
            {
                lock (gate)
                    return IntPtr.Zero != cameFrom;
            }
        }

        internal static bool Return()
        {
            bool retVal = false;
            IntPtr back;
 
            lock (gate)
            {
                back = cameFrom;
                cameFrom = IntPtr.Zero;
            }
 
            if (IntPtr.Zero != back)
            {
                retVal = SwitchDesktop(back);
                CloseDesktop(back);
            }
 
            return retVal;
        }

        internal static string Peek(int forMsEach)
        {
            List<KeyValuePair<string, IntPtr>> walk;
 
            lock (gate)
                walk = desktops.Where(desktop => 0 < WindowCount(desktop.Key)).ToList();
 
            return Walk(walk, forMsEach, "there is nothing on any hidden desktop to look at");
        }

        internal static string PeekOne(string name, int forMs)
        {
            List<KeyValuePair<string, IntPtr>> walk;
 
            lock (gate)
                walk = desktops.Where(desktop => desktop.Key == name && 0 < WindowCount(desktop.Key)).ToList();
 
            return Walk(walk, forMs, $"there is nothing on the hidden desktop [{name}] to look at");
        }

        private static string Walk(List<KeyValuePair<string, IntPtr>> walk, int forMsEach, string nothingToSee)
        {
            string retVal = null;
 
            if (0 == walk.Count)
                retVal = nothingToSee;
            else if (true == IsShowing)
                retVal = "the screen is already on a hidden desktop";
            else
            {
                // the right to switch and nothing more. asking for everything on the desktop the user is on is
                // refused for an ordinary process, and a handle we cannot get is a screen we cannot hand back.
                // taken before the switch, because after it the input desktop is the one we moved to
                IntPtr from = OpenInputDesktop(0, false, DesktopSwitchDesktop);
 
                if (IntPtr.Zero == from)
                    retVal = $"no handle on the desktop you are on [{Marshal.GetLastWin32Error()}], so nothing was switched";
                else
                {
                    lock (gate)
                        cameFrom = from;
 
                    // started before the switch and outliving this process, because everything else here that
                    // hands the screen back needs this process to still be alive to do it
                    Process guard = DesktopGuard.Start(0 < forMsEach ? forMsEach * walk.Count : 0);
 
                    // the walk holds the screen, so it runs on a foreground thread: a process on its way out
                    // waits for the screen to be handed back rather than leaving somebody stranded
                    Thread viewer = new Thread(() =>
                    {
                        try
                        {
                            foreach (KeyValuePair<string, IntPtr> desktop in walk)
                            {
                                // the way out goes up on the desktop before the screen does, so it is already
                                // listening for Escape by the time anyone is looking at it
                                using (Escape escape = Escape.ShowOn(desktop.Value, desktop.Key))
                                {
                                    if (false == SwitchDesktop(desktop.Value))
                                        continue;
 
                                    if (true == escape.WaitToLeave(forMsEach))
                                        break;
                                }
                            }
                        }
                        finally
                        {
                            Return();
                            DesktopGuard.Stop(guard);
                        }
                    });
 
                    viewer.IsBackground = false;
                    viewer.Start();
                }
            }
 
            if (null != retVal)
                GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"Cannot look at the hidden desktops: {retVal}", null, GPALObjectType.Browser);
 
            return retVal;
        }

        internal static void CloseAll()
        {
            // whoever is shutting us down is not the person looking at the screen, so the screen goes back first
            Return();
 
            lock (gate)
            {
                foreach (IntPtr handle in desktops.Values)
                    CloseDesktop(handle);
 
                desktops.Clear();
            }
        }

        internal static void Close(string name)
        {
            lock (gate)
                if (true == desktops.TryGetValue(name, out IntPtr handle))
                {
                    CloseDesktop(handle);
                    desktops.Remove(name);
                }
        }

        private static IntPtr HandleFor(string name)
        {
            IntPtr retVal;
 
            lock (gate)
                desktops.TryGetValue(name, out retVal);
 
            return retVal;
        }

        private sealed class Escape : IDisposable
        {
            private const int HotKeyId = 0xE5CA;
            private const uint VkEscape = 0x1B;
            private const uint ModNoRepeat = 0x4000;
 
            // how long a peek with no clock on it waits when the escape window never came up, because then
            // there is nothing on the screen to leave by and the clock is all that is left
            private const int BlindHoldInMs = 15_000;
 
            // and how long it waits when the escape window did come up. never Timeout.Infinite: a peek with no
            // clock on it still gets one, because a hot key that failed to register and a button behind a
            // fullscreen browser are both ways for a window that exists to not be a way out
            private const int MaxHoldInMs = 600_000;
 
            private readonly ManualResetEvent leaving = new ManualResetEvent(false);
            private readonly ManualResetEvent ready = new ManualResetEvent(false);
            private readonly Thread thread;
 
            private volatile EscapeForm form;
            private volatile bool live;
 
            private Escape(IntPtr desktop, string name)
            {
                thread = new Thread(() =>
                {
                    if (false == SetThreadDesktop(desktop))
                        ready.Set();
                    else
                    {
                        EscapeForm showing = new EscapeForm(name, Leave);
 
                        showing.Shown += (sender, args) =>
                        {
                            live = true;
                            ready.Set();
                        };
 
                        form = showing;
 
                        System.Windows.Forms.Application.Run(showing);
                    }
                });
 
                thread.IsBackground = true;
                thread.SetApartmentState(ApartmentState.STA);
                thread.Start();
            }

            internal static Escape ShowOn(IntPtr desktop, string name)
            {
                Escape retVal = new Escape(desktop, name);
 
                retVal.ready.WaitOne(5_000);
 
                if (false == retVal.live)
                    GPAL.PublishSimpleEvent(GPALEventType.WARNING, $"No way out could be put on the hidden desktop [{name}], so the clock is the only way back",
                        null, GPALObjectType.Browser);
 
                return retVal;
            }

            internal bool WaitToLeave(int forMs)
            {
                bool retVal;
                int limit = 0 < forMs ? forMs : (true == live ? MaxHoldInMs : BlindHoldInMs);
 
                retVal = leaving.WaitOne(limit);
 
                return retVal;
            }

            public void Dispose()
            {
                EscapeForm closing = form;
 
                if (null != closing && true == closing.IsHandleCreated)
                    closing.BeginInvoke(new Action(() => closing.Close()));
 
                thread.Join(5_000);
 
                leaving.Dispose();
                ready.Dispose();
            }

            private void Leave()
            {
                leaving.Set();
            }

            private sealed class EscapeForm : Form
            {
                private const int WmHotKey = 0x0312;
 
                private readonly Action leave;
 
                internal EscapeForm(string desktop, Action leave)
                {
                    this.leave = leave;
 
                    Rectangle screen = Screen.PrimaryScreen.Bounds;
 
                    FormBorderStyle = FormBorderStyle.None;
                    StartPosition = FormStartPosition.Manual;
                    ShowInTaskbar = false;
                    TopMost = true;
                    BackColor = Color.FromArgb(24, 24, 24);
                    ForeColor = Color.White;
                    Padding = new Padding(6);
                    Size = new Size(300, 62);
 
                    // the bottom left corner, because the middle of the screen is where the browser being looked
                    // at is, and this is here to be found rather than to be read
                    Location = new Point(screen.Left + 12, screen.Bottom - Height - 12);
                    KeyPreview = true;
 
                    Button back = new Button
                    {
                        Text = "Return   (Esc)",
                        Dock = DockStyle.Fill,
                        FlatStyle = FlatStyle.System,
                        Font = new Font("Segoe UI", 9F, FontStyle.Bold),
                    };
 
                    Label caption = new Label
                    {
                        Text = desktop,
                        Dock = DockStyle.Top,
                        Height = 18,
                        TextAlign = ContentAlignment.MiddleCenter,
                        Font = new Font("Segoe UI", 8F, FontStyle.Regular),
                    };
 
                    back.Click += (sender, args) => this.leave();
 
                    // the fill goes in before the dock, because docking runs back through the collection
                    Controls.Add(back);
                    Controls.Add(caption);
 
                    KeyDown += (sender, args) =>
                    {
                        if (Keys.Escape == args.KeyCode)
                            this.leave();
                    };
                }
 
                protected override void OnHandleCreated(EventArgs e)
                {
                    base.OnHandleCreated(e);
 
                    // the hot key belongs to this thread, and this thread is on the hidden desktop, so Escape is
                    // only taken there and only for as long as this window is up
                    if (false == RegisterHotKey(Handle, HotKeyId, ModNoRepeat, VkEscape))
                        GPAL.PublishSimpleEvent(GPALEventType.WARNING, "Escape could not be taken on the hidden desktop, so the button is the way out",
                            null, GPALObjectType.Browser, new Win32Exception(Marshal.GetLastWin32Error()));
                }
 
                protected override void OnHandleDestroyed(EventArgs e)
                {
                    UnregisterHotKey(Handle, HotKeyId);
 
                    base.OnHandleDestroyed(e);
                }
 
                protected override void WndProc(ref Message m)
                {
                    if (WmHotKey == m.Msg && HotKeyId == m.WParam.ToInt32())
                        leave();
 
                    base.WndProc(ref m);
                }
            }
        }
    }

    internal class GPALHiddenDesktop : IHiddenDesktop
    {
        internal GPALHiddenDesktop(string name)
        {
            Name = name;
        }

        public string Name { get; }

        public int WindowCount => HiddenDesktop.WindowCount(Name);

        public string Peek() => HiddenDesktop.PeekOne(Name, HiddenDesktop.DefaultPeekMs);

        public string Peek(int forMs) => HiddenDesktop.PeekOne(Name, forMs);

        public void Close() => HiddenDesktop.Close(Name);
    }

    internal class GPALHiddenDesktops : IHiddenDesktops
    {
        public IReadOnlyList<string> Names => HiddenDesktop.Names;

        public IHiddenDesktop this[string desktopName] => new GPALHiddenDesktop(desktopName);

        public int WindowCount => HiddenDesktop.WindowCount();

        public bool IsShowing => HiddenDesktop.IsShowing;

        public string Peek() => HiddenDesktop.Peek(HiddenDesktop.DefaultPeekMs);

        public string Peek(int forMsEach) => HiddenDesktop.Peek(forMsEach);

        public string Peek(string desktopName) => HiddenDesktop.PeekOne(desktopName, HiddenDesktop.DefaultPeekMs);

        public bool Return() => HiddenDesktop.Return();

        public void CloseAll() => HiddenDesktop.CloseAll();
    }
}